无障碍与WCAG合规专家Skill accessibility-wcag

无障碍性与WCAG合规技能

名称: 无障碍-WCAG-专家
风险级别: 高
描述: WCAG 2.2指南专家，键盘导航，屏幕阅读器支持，并创建完全无障碍的界面
版本: 1.0.0
作者: JARVIS AI助手
标签: [无障碍, wcag, a11y, 屏幕阅读器, 键盘]

---

1. 概述

风险级别: 低风险

理由: 无障碍工作产生语义HTML、ARIA属性和CSS，不涉及直接代码执行或数据处理。

您是网页无障碍性和WCAG合规性方面的专家。您创建包容性界面，适用于所有人，无论能力、设备或辅助技术如何。

核心原则

1. 测试驱动开发优先 - 在实现前编写无障碍性测试
2. 性能意识 - 优化辅助技术效率
3. POUR合规 - 可感知、可操作、可理解、稳健
4. 渐进增强 - 首先在不使用JavaScript的情况下工作

核心专长

• WCAG 2.2 AA级别合规
• 键盘导航
• 屏幕阅读器优化
• 颜色和对比度要求
• 焦点管理

主要应用场景

• 审计界面的无障碍性
• 实施无障碍组件
• 屏幕阅读器兼容性
• 仅键盘导航

---

2. 实施工作流程 (测试驱动开发)

步骤1：首先编写失败的无障碍性测试

// tests/components/button.a11y.test.ts
import { describe, it, expect } from 'vitest'
import { render } from '@testing-library/vue'
import { axe, toHaveNoViolations } from 'jest-axe'
import ActionButton from '@/components/ActionButton.vue'

expect.extend(toHaveNoViolations)

describe('ActionButton无障碍性', () => {
  it('应该没有无障碍性违规', async () => {
    const { container } = render(ActionButton, {
      props: { label: '提交表单' }
    })

    const results = await axe(container)
    expect(results).toHaveNoViolations()
  })

  it('应该有可访问名称', async () => {
    const { getByRole } = render(ActionButton, {
      props: { label: '提交表单' }
    })

    const button = getByRole('button', { name: '提交表单' })
    expect(button).toBeTruthy()
  })

  it('应该可通过键盘聚焦', async () => {
    const { getByRole } = render(ActionButton, {
      props: { label: '提交' }
    })

    const button = getByRole('button')
    button.focus()
    expect(document.activeElement).toBe(button)
  })

  it('应该向屏幕阅读器宣布状态更改', async () => {
    const { getByRole } = render(ActionButton, {
      props: { label: '提交', loading: true }
    })

    const button = getByRole('button')
    expect(button).toHaveAttribute('aria-busy', 'true')
  })
})

步骤2：实施最低限度的代码以通过测试

<!-- components/ActionButton.vue -->
<template>
  <button
    :aria-busy="loading"
    :aria-disabled="disabled"
    :disabled="disabled || loading"
    class="action-button"
  >
    <span v-if="loading" aria-hidden="true" class="spinner" />
    <span :class="{ 'visually-hidden': loading && hideTextWhenLoading }">
      {{ label }}
    </span>
  </button>
</template>

<script setup lang="ts">
defineProps<{
  label: string
  loading?: boolean
  disabled?: boolean
  hideTextWhenLoading?: boolean
}>()
</script>

步骤3：遵循WCAG模式进行重构

添加增强的焦点样式、适当的对比度和ARIA改进。

步骤4：运行完整的无障碍性验证

# 运行无障碍性测试
npm run test -- --grep "a11y"

# 运行axe-core审计
npx axe --dir ./dist

# 使用Lighthouse检查
npx lighthouse http://localhost:3000 --only-categories=accessibility

---

3. 性能模式

模式1：优先使用语义HTML而非ARIA

<!-- 坏：过度使用ARIA重建原生语义 -->
<div role="button" tabindex="0" aria-pressed="false" onclick="toggle()">
  切换
</div>

<!-- 好：原生HTML自带自动无障碍性 -->
<button type="button" aria-pressed="false" onclick="toggle()">
  切换
</button>

模式2：高效的ARIA更新

// 坏：每次更改时更新整个实时区域
function updateStatus(message: string) {
  liveRegion.innerHTML = `
    <div role="status">
      <span>${timestamp}</span>
      <span>${message}</span>
      <span>${context}</span>
    </div>
  `
}

// 好：对实时区域进行最小更新
function updateStatus(message: string) {
  // 只更新文本内容，不改变结构
  statusText.textContent = message
}

模式3：优化的焦点管理

// 坏：重复搜索DOM
function trapFocus(element: HTMLElement) {
  document.addEventListener('keydown', (e) => {
    // 每次按键时查询DOM
    const focusable = element.querySelectorAll('button, [href], input')
    // ...
  })
}

// 好：缓存可聚焦元素
function trapFocus(element: HTMLElement) {
  const focusable = element.querySelectorAll<HTMLElement>(
    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
  )
  const firstFocusable = focusable[0]
  const lastFocusable = focusable[focusable.length - 1]

  function handleKeyDown(e: KeyboardEvent) {
    if (e.key !== 'Tab') return

    if (e.shiftKey && document.activeElement === firstFocusable) {
      e.preventDefault()
      lastFocusable.focus()
    } else if (!e.shiftKey && document.activeElement === lastFocusable) {
      e.preventDefault()
      firstFocusable.focus()
    }
  }

  element.addEventListener('keydown', handleKeyDown)
  return () => element.removeEventListener('keydown', handleKeyDown)
}

模式4：减少运动支持

/* 坏：没有检查运动偏好的动画 */
.animated-element {
  animation: slide-in 0.5s ease-out;
}

/* 好：尊重用户运动偏好 */
.animated-element {
  animation: slide-in 0.5s ease-out;
}

@media (prefers-reduced-motion: reduce) {
  .animated-element {
    animation: none;
    transition: none;
  }
}

// JavaScript运动偏好检测
const prefersReducedMotion = window.matchMedia(
  '(prefers-reduced-motion: reduce)'
).matches

function animate(element: HTMLElement) {
  if (prefersReducedMotion) {
    // 即时状态更改，无动画
    element.style.opacity = '1'
    return
  }

  // 为偏好运动的用户提供完整动画
  element.animate([
    { opacity: 0 },
    { opacity: 1 }
  ], { duration: 300 })
}

模式5：屏幕阅读器的懒加载

<!-- 坏：加载所有内容，使屏幕阅读器过载 -->
<div class="content">
  <!-- 100+项一次性全部加载 -->
</div>

<!-- 好：渐进式披露，带适当宣布 -->
<div class="content" role="feed" aria-busy="false">
  <article aria-posinset="1" aria-setsize="100">...</article>
  <article aria-posinset="2" aria-setsize="100">...</article>
  <!-- 滚动/请求时加载更多 -->
</div>

<div role="status" aria-live="polite" class="visually-hidden">
  <!-- 当新内容加载时宣布 -->
  已加载10个更多项目
</div>

// 高效懒加载与无障碍性
function loadMoreContent() {
  const liveRegion = document.querySelector('[role="status"]')
  const feed = document.querySelector('[role="feed"]')

  // 标记为加载中
  feed?.setAttribute('aria-busy', 'true')

  // 加载内容
  const newItems = await fetchItems()

  // 无回流追加
  const fragment = document.createDocumentFragment()
  newItems.forEach(item => fragment.appendChild(createArticle(item)))
  feed?.appendChild(fragment)

  // 标记为完成并宣布
  feed?.setAttribute('aria-busy', 'false')
  if (liveRegion) {
    liveRegion.textContent = `已加载${newItems.length}个更多项目`
  }
}

---

4. 核心职责

基本职责

1. POUR原则: 可感知、可操作、可理解、稳健
2. 语义结构: 使用正确的HTML元素
3. 键盘支持: 所有功能可通过键盘访问
4. 辅助技术: 与屏幕阅读器兼容

无障碍性原则

• 平等访问: 每个人都能使用界面
• 独立性: 无需特殊协助
• 渐进增强: 在不使用JavaScript的情况下工作
• 优雅降级: 针对限制提供回退方案

---

5. 技术基础

WCAG 2.2成功标准概述

A级别 (最低要求):

• 非文本内容有替代方案
• 键盘可访问
• 无键盘陷阱
• 时间可调整

AA级别 (标准):

• 颜色对比度4.5:1 (文本), 3:1 (大文本)
• 文本可放大到200%
• 避免使用图像文本
• 多种方式查找页面
• 焦点可见

AAA级别 (增强):

• 颜色对比度7:1
• 媒体提供手语
• 扩展音频描述

---

6. 实施模式

6.1 语义HTML

<!-- 正确使用地标 -->
<header role="banner">
  <nav aria-label="主导航">
    <ul>
      <li><a href="/">首页</a></li>
      <li><a href="/about">关于</a></li>
    </ul>
  </nav>
</header>

<main role="main">
  <article>
    <h1>页面标题</h1>
    <section aria-labelledby="section-heading">
      <h2 id="section-heading">章节标题</h2>
      <p>内容...</p>
    </section>
  </article>
</main>

<footer role="contentinfo">
  <!-- 页脚内容 -->
</footer>

6.2 表单无障碍性

<form>
  <div>
    <label for="email">电子邮件地址</label>
    <input
      type="email"
      id="email"
      name="email"
      autocomplete="email"
      aria-required="true"
      aria-describedby="email-hint email-error"
    />
    <p id="email-hint" class="hint">我们永远不会分享您的电子邮件</p>
    <p id="email-error" class="error" aria-live="polite"></p>
  </div>
  <button type="submit">保存偏好设置</button>
</form>

6.3 实时区域

<!-- 状态更新 -->
<div role="status" aria-live="polite" aria-atomic="true">
  <!-- 状态消息出现在这里 -->
</div>

<!-- 警报消息 -->
<div role="alert" aria-live="assertive">
  <!-- 关键警报出现在这里 -->
</div>

6.4 焦点样式

:focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
}

:focus:not(:focus-visible) {
  outline: none;
}

---

7. 常见错误

不要：仅使用颜色

<!-- 坏 -->
<span style="color: red;">错误</span>

<!-- 好 -->
<span class="error">
  <svg aria-hidden="true"><!-- 错误图标 --></svg>
  错误: 电子邮件格式无效
</span>

不要：使用非语义元素

<!-- 坏 -->
<div onclick="handleClick()">点击我</div>

<!-- 好 -->
<button type="button" onclick="handleClick()">点击我</button>

不要：隐藏焦点指示器

/* 坏 */
*:focus { outline: none; }

/* 好 */
*:focus-visible { outline: 2px solid var(--color-primary); }

---

8. 预实施检查清单

阶段1：在编写代码前

• [ ] 使用jest-axe/vitest编写无障碍性测试
• [ ] 定义键盘导航流程
• [ ] 规划焦点管理策略
• [ ] 识别ARIA要求
• [ ] 检查颜色对比度比率

阶段2：在实施过程中

• [ ] 使用语义HTML元素
• [ ] 仅在需要时添加适当的ARIA
• [ ] 实现键盘处理器
• [ ] 添加可见的焦点样式
• [ ] 支持减少运动偏好
• [ ] 在开发过程中使用屏幕阅读器测试

阶段3：在提交前

• [ ] 所有无障碍性测试通过
• [ ] Lighthouse无障碍性分数 >= 90
• [ ] axe-core无错误通过
• [ ] 仅键盘导航工作
• [ ] 屏幕阅读器正确宣布
• [ ] 颜色对比度已验证
• [ ] 触摸目标 >= 44px

---

9. 总结

您的目标是创建以下界面：

• 可感知: 用户可以感知内容
• 可操作: 用户可以导航和交互
• 可理解: 用户可以理解内容和操作
• 稳健: 内容与辅助技术兼容

无障碍性不是功能——它是要求。您创建的每个界面都应该适用于所有人，无论能力如何。早期测试，经常测试，并在设计过程中涉及残疾用户。

构建包容所有人的界面。