accessibility

无障碍（WCAG 2.2 AA）

核心原则

• 使用语义化 HTML 元素和 ARIA 地标
• 优先支持键盘导航，并显示焦点状态
• 在布局中为主要内容提供跳转链接
• 使用包容、以人为本的语言

语义化 HTML

使用 <header>、<nav aria-label="...">、<main id="main-content">、<section aria-labelledby="...">、<footer>。始终遵循标题层级（h1 → h2 → h3）。

跳转链接

<a href="#main-content" class="sr-only focus:not-sr-only focus:absolute ...">
    Skip to main content
</a>

表单无障碍

• 为每个控件添加标签：使用 <label for="email">，或为仅含图标的输入框添加 aria-label
• 必填字段：使用 required aria-required="true"，并显示 *（aria-hidden="true"）
• 错误消息：通过 aria-describedby 关联，并设置 aria-invalid={hasError}
• 验证失败时：聚焦第一个无效输入框
• 切勿仅为阻止验证而禁用提交

<input id="email" aria-invalid={hasError} aria-describedby={hasError ? 'email-error' : undefined} />
{#if hasError}
    <p id="email-error" class="text-destructive">Please enter a valid email address</p>
{/if}

键盘导航

• 自然 Tab 顺序遵循 DOM 顺序 — 避免使用正数 tabindex
• 对隐藏或非活动元素使用 tabindex="-1"
• 对话框：打开时聚焦第一个可交互元素，关闭时将焦点还给触发元素
• 非按钮的可交互元素必须处理 Enter 和 Space 键事件

图标按钮

始终添加 aria-label，并对辅助技术隐藏图标：

<button aria-label="Delete event">
    <TrashIcon aria-hidden="true" />
</button>

图标与可见文本同时出现时，只需隐藏图标：<PlusIcon aria-hidden="true" />。

ARIA 模式

用于动态更新的实时区域：

<div aria-live="polite" aria-atomic="true">{#if loading}Loading events...{/if}</div>
<div role="alert">Error: Failed to save changes</div>

可展开内容：在触发元素上使用 aria-expanded 和 aria-controls，并在面板上使用 hidden。

颜色与对比度

• 最低对比度：普通文本为 4.5:1，大号文本和 UI 组件为 3:1
• 不要仅依赖颜色 — 同时使用图标或文本

<span class="text-destructive"><AlertIcon aria-hidden="true" /> Error: Invalid input</span>

测试

在 E2E 测试中使用 axe-playwright（AxeBuilder({ page }).analyze()）检测无障碍违规问题。