Communitygithub.com

ulasalyesil/personal-website-v2

執行 WCAG 2.2 無障礙審計,包含自動化測試、手動驗證與修復指引。適用於網站無障礙審計、修正 WCAG 違規或實作無障礙設計模式。

personal-website-v2 是什麼?

此技能提供全面的 WCAG 2.2 無障礙審計指南,涵蓋自動化測試、手動驗證與修復策略。它基於 POUR 原則(可感知、可操作、可理解、穩健)組織,並詳細列出每個成功標準的檢查清單,包括 A、AA、AAA 三個符合等級。技能支援多種工具整合,如 axe-core、Playwright、Pa11y 和 Lighthouse,並提供常見違規(如表單標籤缺失、色彩對比不足、鍵盤導航問題)的具體修復範例。適合開發者、QA 測試人員與合規團隊使用,尤其適用於 ADA/Section 508 合規或 VPAT 準備工作。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ulasalyesil/personal-website-v2/tree/HEAD/.agent/skills/wcag-audit-patterns

在你喜歡的 AI 中提問

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

預覽

來自技能 README

personal-website-v2 preview
personal-website-v2 preview

說明文件

WCAG 審計模式

全面的網頁內容 WCAG 2.2 無障礙審計指南,附帶可行的修復策略。

何時使用此技能

  • 執行無障礙審計
  • 修正 WCAG 違規
  • 實作無障礙元件
  • 準備因應無障礙訴訟
  • 滿足 ADA/Section 508 要求
  • 達成 VPAT 合規

核心概念

1. WCAG 符合等級

等級描述要求對象
A最低無障礙法律基準
AA標準符合大多數法規
AAA強化無障礙特殊需求

2. POUR 原則

可感知:使用者能否感知內容?
可操作:使用者能否操作介面?
可理解:使用者能否理解內容?
穩健:是否能與輔助技術相容?

3. 常見違規按影響程度分級

嚴重(阻斷者):
├── 功能性圖片缺少替代文字
├── 互動元素無鍵盤存取
├── 缺少表單標籤
└── 無控制項的自動播放媒體

嚴重:
├── 色彩對比不足
├── 缺少跳過連結
├── 無法存取的客製化小工具
└── 缺少頁面標題

中等:
├── 缺少語言屬性
├── 不明確的連結文字
├── 缺少地標
└── 不當的標題層級

審計檢查清單

可感知(原則 1)

1.1 文字替代

1.1.1 非文字內容(等級 A)
  • 所有圖片皆有替代文字
  • 裝飾性圖片使用 alt=""
  • 複雜圖片有長描述
  • 具有意義的圖示有可存取的名稱
  • CAPTCHA 有替代方案

檢查:

<!-- 良好 -->
<img src="chart.png" alt="銷售額從第一季到第二季成長了 25%" />
<img src="decorative-line.png" alt="" />

<!-- 不良 -->
<img src="chart.png" />
<img src="decorative-line.png" alt="裝飾線條" />

1.2 基於時間的媒體

1.2.1 純音訊與純視訊(等級 A)
  • 音訊附有文字逐字稿
  • 視訊附有口述影像或逐字稿
1.2.2 字幕(等級 A)
  • 所有視訊皆有同步字幕
  • 字幕準確且完整
  • 包含說話者識別
1.2.3 口述影像(等級 A)
  • 視訊針對視覺內容提供口述影像

1.3 可調適

1.3.1 資訊與關係(等級 A)
  • 標題使用適當標籤(h1-h6)
  • 清單使用 ul/ol/dl
  • 表格有表頭
  • 表單輸入有標籤
  • ARIA 地標存在

檢查:

<!-- 標題層級 -->
<h1>頁面標題</h1>
<h2>章節</h2>
<h3>子章節</h3>
<h2>另一個章節</h2>

<!-- 表格表頭 -->
<table>
  <thead>
    <tr>
      <th scope="col">姓名</th>
      <th scope="col">價格</th>
    </tr>
  </thead>
</table>
1.3.2 有意義的順序(等級 A)
  • 閱讀順序符合邏輯
  • CSS 定位不破壞順序
  • 焦點順序與視覺順序一致
1.3.3 感官特性(等級 A)
  • 指示不單獨依賴形狀/顏色
  • 「點擊紅色按鈕」→「點擊提交(紅色按鈕)」

1.4 可辨識

1.4.1 顏色的使用(等級 A)
  • 顏色不是傳達資訊的唯一方式
  • 連結不需依賴顏色即可辨識
  • 錯誤狀態不僅以顏色表示
1.4.3 對比(最低)(等級 AA)
  • 文字:對比度 4.5:1
  • 大字型(18pt+):對比度 3:1
  • UI 元件:對比度 3:1

工具:WebAIM 對比檢查器、axe DevTools

1.4.4 調整文字大小(等級 AA)
  • 文字可放大至 200% 而不遺失
  • 在 320px 寬度下無水平捲動
  • 內容能正確重新排列
1.4.10 重新排列(等級 AA)
  • 內容在 400% 縮放下能重新排列
  • 無雙軸捲動
  • 所有內容在 320px 寬度下可存取
1.4.11 非文字對比(等級 AA)
  • UI 元件具有 3:1 的對比度
  • 焦點指示器可見
  • 圖形物件可區分
1.4.12 文字間距(等級 AA)
  • 增加間距後內容無遺失
  • 行高為字型大小的 1.5 倍
  • 段落間距為字型大小的 2 倍
  • 字母間距為字型大小的 0.12 倍
  • 字詞間距為字型大小的 0.16 倍

可操作(原則 2)

2.1 鍵盤可存取

2.1.1 鍵盤(等級 A)
  • 所有功能皆可透過鍵盤存取
  • 無鍵盤陷阱
  • Tab 順序符合邏輯
  • 客製化小工具可經由鍵盤操作

檢查:

// 自訂按鈕必須可透過鍵盤存取
<div role="button" tabindex="0"
     onkeydown="if(event.key === 'Enter' || event.key === ' ') activate()">
2.1.2 無鍵盤陷阱(等級 A)
  • 焦點可以從所有元件中移開
  • 模態對話框正確地限制焦點
  • 關閉模態後焦點返回

2.2 足夠時間

2.2.1 時間調整(等級 A)
  • 工作階段逾時可延長
  • 逾時前警告使用者
  • 可選擇停用自動重新整理
2.2.2 暫停、停止、隱藏(等級 A)
  • 移動的內容可以暫停
  • 自動更新的內容可以暫停
  • 動畫尊重 prefers-reduced-motion
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}

2.3 癲癇與生理反應

2.3.1 三次閃爍(等級 A)
  • 內容閃爍頻率不超過每秒 3 次
  • 閃爍區域小(<25% 視口)

2.4 可導航

2.4.1 跳過區塊(等級 A)
  • 存在「跳至主要內容」連結
  • 定義了地標區域
  • 適當的標題結構
<a href="#main" class="skip-link">跳至主要內容</a>
<main id="main">...</main>
2.4.2 頁面標題(等級 A)
  • 獨特且具描述性的頁面標題
  • 標題反映頁面內容
2.4.3 焦點順序(等級 A)
  • 焦點順序與視覺順序一致
  • 正確使用 tabindex
2.4.4 連結目的(在脈絡中)(等級 A)
  • 連結脫離脈絡後仍有意義
  • 不使用單獨的「點此」或「閱讀更多」
<!-- 不良 -->
<a href="report.pdf">點此</a>

<!-- 良好 -->
<a href="report.pdf">下載第四季銷售報告(PDF)</a>
2.4.6 標題與標籤(等級 AA)
  • 標題描述內容
  • 標籤描述目的
2.4.7 焦點可見(等級 AA)
  • 所有元素上焦點指示器可見
  • 自訂焦點樣式符合對比度
:focus {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}
2.4.11 焦點未被遮蔽(等級 AA)- WCAG 2.2
  • 焦點元素未被完全隱藏
  • 固定頁首不遮蔽焦點

可理解(原則 3)

3.1 可讀性

3.1.1 頁面語言(等級 A)
  • 設定了 HTML lang 屬性
  • 語言與內容相符
<html lang="zh-TW">
3.1.2 部分語言(等級 AA)
  • 標記語言變換
<p>法語單字 <span lang="fr">bonjour</span> 意為「你好」。</p>

3.2 可預測

3.2.1 獲取焦點(等級 A)
  • 單獨獲取焦點不引發脈絡變化
  • 獲取焦點時不出現意外的彈出視窗
3.2.2 輸入(等級 A)
  • 不會自動提交表單
  • 脈絡變更前警告使用者
3.2.3 一致的導航(等級 AA)
  • 導航方式在頁面間一致
  • 重複元件保持相同順序
3.2.4 一致的身份識別(等級 AA)
  • 相同功能使用相同標籤
  • 圖示使用一致

3.3 輸入輔助

3.3.1 錯誤識別(等級 A)
  • 錯誤清楚標示
  • 錯誤訊息描述問題
  • 錯誤與欄位關聯
<input aria-describedby="email-error" aria-invalid="true" />
<span id="email-error" role="alert">請輸入有效的電子郵件</span>
3.3.2 標籤或指示(等級 A)
  • 所有輸入皆有可見標籤
  • 標示必填欄位
  • 提供格式提示
3.3.3 錯誤建議(等級 AA)
  • 錯誤訊息包含修正建議
  • 建議具體明確
3.3.4 錯誤預防(等級 AA)
  • 法律/財務表單可復原
  • 提交前檢查資料
  • 使用者可在提交前審閱

穩健(原則 4)

4.1 相容性

4.1.1 解析(等級 A)- 在 WCAG 2.2 中已廢棄
  • 有效的 HTML(良好做法)
  • 無重複 ID
  • 完整的起始/結束標籤
4.1.2 名稱、角色、數值(等級 A)
  • 客製化小工具具有可存取的名稱
  • ARIA 角色正確
  • 狀態變更會公告
<!-- 可存取的客製化核取方塊 -->
<div role="checkbox"
     aria-checked="false"
     tabindex="0"
     aria-labelledby="label">
</div>
<span id="label">接受條款</span>
4.1.3 狀態訊息(等級 AA)
  • 狀態更新會公告
  • 正確使用動態區域
<div role="status" aria-live="polite">已將 3 個項目加入購物車</div>

<div role="alert" aria-live="assertive">錯誤:表單提交失敗</div>

自動化測試

// axe-core 整合
const axe = require('axe-core');

async function runAccessibilityAudit(page) {
  await page.addScriptTag({ path: require.resolve('axe-core') });

  const results = await page.evaluate(async () => {
    return await axe.run(document, {
      runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa']
      }
    });
  });

  return {
    violations: results.violations,
    passes: results.passes,
    incomplete: results.incomplete
  };
}

// Playwright 測試範例
test('應無無障礙違規', async ({ page }) => {
  await page.goto('/');
  const results = await runAccessibilityAudit(page);

  expect(results.violations).toHaveLength(0);
});
# CLI 工具
npx @axe-core/cli https://example.com
npx pa11y https://example.com
lighthouse https://example.com --only-categories=accessibility

修復模式

修正:缺少表單標籤

<!-- 改善前 -->
<input type="email" placeholder="電子郵件" />

<!-- 改善後:選項 1 - 可見標籤 -->
<label for="email">電子郵件地址</label>
<input id="email" type="email" />

<!-- 改善後:選項 2 - aria-label -->
<input type="email" aria-label="電子郵件地址" />

<!-- 改善後:選項 3 - aria-labelledby -->
<span id="email-label">電子郵件</span>
<input type="email" aria-labelledby="email-label" />

修正:色彩對比不足

/* 改善前:2.5:1 對比 */
.text {
  color: #767676;
}

/* 改善後:4.5:1 對比 */
.text {
  color: #595959;
}

/* 或加入背景 */
.text {
  color: #767676;
  background: #000;
}

修正:鍵盤導航

// 讓自訂元素可透過鍵盤存取
class AccessibleDropdown extends HTMLElement {
  connectedCallback() {
    this.setAttribute("tabindex", "0");
    this.setAttribute("role", "combobox");
    this.setAttribute("aria-expanded", "false");

    this.addEventListener("keydown", (e) => {
      switch (e.key) {
        case "Enter":
        case " ":
          this.toggle();
          e.preventDefault();
          break;
        case "Escape":
          this.close();
          break;
        case "ArrowDown":
          this.focusNext();
          e.preventDefault();
          break;
        case "ArrowUp":
          this.focusPrevious();
          e.preventDefault();
          break;
      }
    });
  }
}

最佳實踐

應做事項

  • 盡早開始 - 從設計階段就考慮無障礙
  • 與真實使用者測試 - 身心障礙使用者提供最佳回饋
  • 盡量自動化 - 可檢測 30-50% 的問題
  • 使用語意化 HTML - 減少 ARIA 的需求
  • 記錄模式 - 建立可存取的元件庫

不應做事項

  • 不要僅依賴自動化測試 - 仍需手動測試
  • 不要將 ARIA 作為首要解決方案 - 優先使用原生 HTML
  • 不要隱藏焦點外框 - 鍵盤使用者需要它們
  • 不要停用縮放 - 使用者需要調整大小
  • 不要只使用顏色 - 需要多重指示器

資源

Individual skills in this repo

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

ulasalyesil/personal-website-v2

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.

ulasalyesil/personal-website-v2

Conduct design interviews, generate five distinct UI variations in a temporary design lab, collect feedback, and produce implementation plans. Use when the user wants to explore UI design options, redesign existing components, or create new UI with multiple approaches to compare.

ulasalyesil/personal-website-v2

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

ulasalyesil/personal-website-v2

Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.

ulasalyesil/personal-website-v2

This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).

ulasalyesil/personal-website-v2

Best practices and example-driven guidance for building SwiftUI views and components. Use when creating or refactoring SwiftUI UI, designing tab architecture with TabView, composing screens, or needing component-specific patterns and examples.

ulasalyesil/personal-website-v2

UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 9 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient. Integrations: shadcn/ui MCP for component search and examples.

ulasalyesil/personal-website-v2

Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".

ulasalyesil/personal-website-v2

Enforces an opinionated UI baseline to prevent AI-generated interface slop.

ulasalyesil/personal-website-v2

Build modern, composable, and accessible React UI components following the components.build specification. Use when creating, reviewing, or refactoring component libraries, design systems, or any reusable UI components. Triggers on tasks involving component APIs, composition patterns, accessibility, styling systems, or TypeScript props.

ulasalyesil/personal-website-v2

Ship correct, complete metadata.

ulasalyesil/personal-website-v2

Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement.

ulasalyesil/personal-website-v2

Defines the product's objects, relationships, states, and vocabulary independently of any interface — the most load-bearing layer

ulasalyesil/personal-website-v2

Maps domain concepts, terminology conflicts, and bounded contexts — produces a noun harvest for the conceptual model layer

ulasalyesil/personal-website-v2

Maps interaction structure and flow — produces breadboard notation with edge cases, failure paths, and open decisions

ulasalyesil/personal-website-v2

Framework orientation for Layers of Product Design — load this first; provides the context all other skills depend on

ulasalyesil/personal-website-v2

User research planning and synthesis at the observed behaviour layer — produces candidate job stories with confidence ratings

ulasalyesil/personal-website-v2

Diagnostic audit across all seven layers — identifies the bottleneck layer and recommends where to focus

ulasalyesil/personal-website-v2

Connects user opportunities to business outcomes and solution bets — produces a strategy tree and prioritised experiments

ulasalyesil/personal-website-v2

Audits existing surface against lower-layer decisions and produces a surface decision inventory — vocabulary, object consistency, completeness, feedback, hierarchy, accessibility

相關技能