可访问性合规Skill accessibility-compliance

---

名称：可访问性合规 描述：实现符合WCAG 2.2标准的接口，支持移动可访问性、包容性设计模式和辅助技术。用于审核可访问性、实现ARIA模式、构建屏幕阅读器兼容界面或确保包容性用户体验。

可访问性合规

掌握可访问性实现，创建包容性体验，适用于所有人，包括残障用户。

何时使用此技能

• 实现WCAG 2.2 Level AA或AAA合规
• 构建屏幕阅读器可访问的界面
• 为交互组件添加键盘导航
• 实现焦点管理和焦点陷阱
• 创建带正确标签的可访问表单
• 支持减少动画和高对比度偏好
• 构建移动可访问性功能（iOS VoiceOver、Android TalkBack）
• 进行可访问性审核并修复违规

核心能力

1. WCAG 2.2指南

• 可感知：内容必须以不同方式呈现
• 可操作：界面必须可通过键盘和辅助技术导航
• 可理解：内容和操作必须清晰
• 健壮：内容必须与当前和未来的辅助技术兼容

2. ARIA模式

• 角色：定义元素目的（按钮、对话框、导航）
• 状态：指示当前条件（展开、选中、禁用）
• 属性：描述关系和附加信息（labelledby、describedby）
• 实时区域：宣布动态内容变化

3. 键盘导航

• 焦点顺序和Tab序列
• 焦点指示器和可见焦点状态
• 键盘快捷键和热键
• 模态和对话框的焦点陷阱

4. 屏幕阅读器支持

• 语义HTML结构
• 图像的替代文本
• 正确的标题层次结构
• 跳过链接和地标

5. 移动可访问性

• 触摸目标大小（最小44x44dp）
• VoiceOver和TalkBack兼容性
• 手势替代方案
• 动态类型支持

快速参考

WCAG 2.2成功标准检查清单

等级	标准	描述
A	1.1.1	非文本内容有文本替代
A	1.3.1	信息和关系可程序化确定
A	2.1.1	所有功能键盘可访问
A	2.4.1	跳过到主要内容的机制
AA	1.4.3	对比度比率4.5:1（文本）、3:1（大文本）
AA	1.4.11	非文本对比度3:1
AA	2.4.7	焦点可见
AA	2.5.8	目标大小最小24x24px（WCAG 2.2新增）
AAA	1.4.6	增强对比度7:1
AAA	2.5.5	目标大小最小44x44px

关键模式

模式1：可访问按钮

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary";
  isLoading?: boolean;
}

function AccessibleButton({
  children,
  variant = "primary",
  isLoading = false,
  disabled,
  ...props
}: ButtonProps) {
  return (
    <button
      // 加载时禁用
      disabled={disabled || isLoading}
      // 向屏幕阅读器宣布加载状态
      aria-busy={isLoading}
      // 描述按钮的当前状态
      aria-disabled={disabled || isLoading}
      className={cn(
        // 可见焦点环
        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2",
        // 最小触摸目标大小（44x44px）
        "min-h-[44px] min-w-[44px]",
        variant === "primary" && "bg-primary text-primary-foreground",
        (disabled || isLoading) && "opacity-50 cursor-not-allowed",
      )}
      {...props}
    >
      {isLoading ? (
        <>
          <span className="sr-only">加载中</span>
          <Spinner aria-hidden="true" />
        </>
      ) : (
        children
      )}
    </button>
  );
}

模式2：可访问模态对话框

import * as React from "react";
import { FocusTrap } from "@headlessui/react";

interface DialogProps {
  isOpen: boolean;
  onClose: () => void;
  title: string;
  children: React.ReactNode;
}

function AccessibleDialog({ isOpen, onClose, title, children }: DialogProps) {
  const titleId = React.useId();
  const descriptionId = React.useId();

  // 按Escape键关闭
  React.useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === "Escape" && isOpen) {
        onClose();
      }
    };
    document.addEventListener("keydown", handleKeyDown);
    return () => document.removeEventListener("keydown", handleKeyDown);
  }, [isOpen, onClose]);

  // 打开时防止正文滚动
  React.useEffect(() => {
    if (isOpen) {
      document.body.style.overflow = "hidden";
    }
    return () => {
      document.body.style.overflow = "";
    };
  }, [isOpen]);

  if (!isOpen) return null;

  return (
    <div
      role="dialog"
      aria-modal="true"
      aria-labelledby={titleId}
      aria-describedby={descriptionId}
    >
      {/* 背景 */}
      <div
        className="fixed inset-0 bg-black/50"
        aria-hidden="true"
        onClick={onClose}
      />

      {/* 焦点陷阱容器 */}
      <FocusTrap>
        <div className="fixed inset-0 flex items-center justify-center p-4">
          <div className="bg-background rounded-lg shadow-lg max-w-md w-full p-6">
            <h2 id={titleId} className="text-lg font-semibold">
              {title}
            </h2>
            <div id={descriptionId}>{children}</div>
            <button
              onClick={onClose}
              className="absolute top-4 right-4"
              aria-label="关闭对话框"
            >
              <X className="h-4 w-4" />
            </button>
          </div>
        </div>
      </FocusTrap>
    </div>
  );
}

模式3：可访问表单

function AccessibleForm() {
  const [errors, setErrors] = React.useState<Record<string, string>>({});

  return (
    <form aria-describedby="form-errors" noValidate>
      {/* 屏幕阅读器的错误摘要 */}
      {Object.keys(errors).length > 0 && (
        <div
          id="form-errors"
          role="alert"
          aria-live="assertive"
          className="bg-destructive/10 border border-destructive p-4 rounded-md mb-4"
        >
          <h2 className="font-semibold text-destructive">
            请修复以下错误：
          </h2>
          <ul className="list-disc list-inside mt-2">
            {Object.entries(errors).map(([field, message]) => (
              <li key={field}>
                <a href={`#${field}`} className="underline">
                  {message}
                </a>
              </li>
            ))}
          </ul>
        </div>
      )}

      {/* 带错误的必填字段 */}
      <div className="space-y-2">
        <label htmlFor="email" className="block font-medium">
          电子邮件地址
          <span aria-hidden="true" className="text-destructive ml-1">
            *
          </span>
          <span className="sr-only">（必填）</span>
        </label>
        <input
          id="email"
          name="email"
          type="email"
          required
          aria-required="true"
          aria-invalid={!!errors.email}
          aria-describedby={errors.email ? "email-error" : "email-hint"}
          className={cn(
            "w-full px-3 py-2 border rounded-md",
            errors.email && "border-destructive",
          )}
        />
        {errors.email ? (
          <p id="email-error" className="text-sm text-destructive" role="alert">
            {errors.email}
          </p>
        ) : (
          <p id="email-hint" className="text-sm text-muted-foreground">
            我们永远不会分享您的电子邮件。
          </p>
        )}
      </div>

      <button type="submit" className="mt-4">
        提交
      </button>
    </form>
  );
}

模式4：跳过导航链接

function SkipLink() {
  return (
    <a
      href="#main-content"
      className={cn(
        // 默认隐藏，聚焦时可见
        "sr-only focus:not-sr-only",
        "focus:absolute focus:top-4 focus:left-4 focus:z-50",
        "focus:bg-background focus:px-4 focus:py-2 focus:rounded-md",
        "focus:ring-2 focus:ring-primary",
      )}
    >
      跳到主要内容
    </a>
  );
}

// 在布局中
function Layout({ children }) {
  return (
    <>
      <SkipLink />
      <header>...</header>
      <nav aria-label="主要导航">...</nav>
      <main id="main-content" tabIndex={-1}>
        {children}
      </main>
      <footer>...</footer>
    </>
  );
}

模式5：用于宣布的实时区域

function useAnnounce() {
  const [message, setMessage] = React.useState("");

  const announce = React.useCallback(
    (text: string, priority: "polite" | "assertive" = "polite") => {
      setMessage(""); // 先清除以确保重新宣布
      setTimeout(() => setMessage(text), 100);
    },
    [],
  );

  const Announcer = () => (
    <div
      role="status"
      aria-live="polite"
      aria-atomic="true"
      className="sr-only"
    >
      {message}
    </div>
  );

  return { announce, Announcer };
}

// 用法
function SearchResults({ results, isLoading }) {
  const { announce, Announcer } = useAnnounce();

  React.useEffect(() => {
    if (!isLoading && results) {
      announce(`${results.length} 个结果找到`);
    }
  }, [results, isLoading, announce]);

  return (
    <>
      <Announcer />
      <ul>{/* 结果 */}</ul>
    </>
  );
}

颜色对比度要求

// 对比度比率实用工具
function getContrastRatio(foreground: string, background: string): number {
  const fgLuminance = getLuminance(foreground);
  const bgLuminance = getLuminance(background);
  const lighter = Math.max(fgLuminance, bgLuminance);
  const darker = Math.min(fgLuminance, bgLuminance);
  return (lighter + 0.05) / (darker + 0.05);
}

// WCAG要求
const CONTRAST_REQUIREMENTS = {
  // 正常文本（<18pt或<14pt粗体）
  normalText: {
    AA: 4.5,
    AAA: 7,
  },
  // 大文本（>=18pt或>=14pt粗体）
  largeText: {
    AA: 3,
    AAA: 4.5,
  },
  // UI组件和图形
  uiComponents: {
    AA: 3,
  },
};

最佳实践

1. 使用语义HTML：尽可能使用原生元素而非ARIA
2. 与真实用户测试：在用户测试中包括残障人士
3. 键盘优先：设计无需鼠标的交互
4. 不要禁用焦点样式：样式化它们，不要移除
5. 提供文本替代：所有非文本内容都需要描述
6. 支持缩放：内容应在200%缩放下工作
7. 宣布变化：使用实时区域处理动态内容
8. 尊重偏好：尊重prefers-reduced-motion和prefers-contrast

常见问题

• 缺失alt文本：图像没有描述
• 颜色对比度差：文本难以阅读
• 键盘陷阱：焦点卡在组件中
• 缺失标签：表单输入没有关联标签
• 自动播放媒体：内容无需用户启动即播放
• 不可访问的自定义控件：重新创建原生功能差
• 缺失跳过链接：无法绕过重复内容
• 焦点顺序问题：Tab顺序与视觉顺序不匹配

测试工具

• 自动化：axe DevTools、WAVE、Lighthouse
• 手动：VoiceOver（macOS/iOS）、NVDA/JAWS（Windows）、TalkBack（Android）
• 模拟器：NoCoffee（视觉）、Silktide（各种残障）

资源

• WCAG 2.2指南
• WAI-ARIA编写实践
• A11y项目检查清单
• 包容性组件
• Deque大学