frontend-accessibility-best-practices

无障碍最佳实践

遵循 WCAG 标准构建包容性 React 应用的无障碍模式。包含 4 个类别中的 7 条规则，重点关注语义化 HTML、屏幕阅读器支持、键盘导航和用户偏好。

适用场景

以下情况请参考这些指南：

• 创建新的 UI 组件
• 构建表单和交互元素
• 添加动态内容或通知
• 实现导航模式
• 检查代码的无障碍性

规则摘要

语义化 HTML 与结构（高）

semantic-html-landmarks - @rules/semantic-html-landmarks.md

使用语义化 HTML 元素构建页面结构。

// Bad: divs with class names
<div className="header">...</div>
<div className="nav">...</div>
<div className="content">...</div>

// Good: semantic elements
<header>...</header>
<nav aria-label={t("Primary")}>...</nav>
<main>...</main>
<footer>...</footer>

屏幕阅读器（中）

screen-reader-sr-only - @rules/screen-reader-sr-only.md

使用 sr-only 类隐藏视觉上不可见的文本。

// Icon-only buttons need accessible labels
<Button variant="icon" onPress={onClose}>
  <XMarkIcon aria-hidden="true" />
  <span className="sr-only">{t("Close")}</span>
</Button>

// Visually hidden section headings
<section>
  <h2 className="sr-only">{t("Search results")}</h2>
  <SearchResultsList />
</section>

aria-live-regions - @rules/aria-live-regions.md

向屏幕阅读器播报动态内容的变化。

// Error messages - announced immediately
{
  error && (
    <p role="alert" className="text-failure-600">
      {error}
    </p>
  );
}

// Status updates - announced politely
<div role="status" aria-live="polite">
  {t("{{count}} results found", { count })}
</div>;

键盘与焦点（高）

keyboard-navigation - @rules/keyboard-navigation.md

使用语义化元素提供内置键盘支持。

// Bad: div with onClick not keyboard accessible
<div onClick={handleClick}>Click me</div>

// Good: button has Enter/Space support
<button onClick={handleClick}>Click me</button>

// Good: react-aria Button handles everything
import { Button } from "react-aria-components";
<Button onPress={handlePress}>Click me</Button>

focus-management - @rules/focus-management.md

显示清晰可见的焦点指示器，并在模态框中锁定焦点。

// Always use focus-visible for focus styles
<button className="focus-visible:ring-2 focus-visible:ring-teal-600">
  Click me
</button>;

// react-aria Modal handles focus trapping automatically
import { Modal, Dialog } from "react-aria-components";
<Modal isOpen={isOpen}>
  <Dialog>{/* Focus automatically trapped here */}</Dialog>
</Modal>;

用户偏好（中）

reduced-motion - @rules/reduced-motion.md

遵循 prefers-reduced-motion 设置。

import { usePrefersReducedMotion } from "~/hooks/use-prefers-reduced-motion";

// CSS approach
<div className="animate-bounce motion-reduce:animate-none">
  Bouncing content
</div>;

// JS approach
function AnimatedCounter({ value }) {
  let prefersReducedMotion = usePrefersReducedMotion();
  if (prefersReducedMotion) return <span>{value}</span>;
  return <CountUp target={value} />;
}

touch-targets - @rules/touch-targets.md

确保触控目标至少为 44x44px。

// Icon buttons need explicit sizing
<Button variant="icon" className="h-11 w-11">
  <XMarkIcon className="h-5 w-5" />
  <span className="sr-only">{t("Close")}</span>
</Button>

// Links need padding for tappable area
<Link to={href} className="block py-3 px-4">
  {label}
</Link>

关键文件

• app/components/heading.tsx - Region、Heading、Main 组件
• app/hooks/use-prefers-reduced-motion.ts - 减少动态效果的 Hook
• app/components/field/field.tsx - 无障碍表单字段组件