a11y

系统性地改进无障碍体验，让有残障、暂时性障碍的用户以及辅助技术都能正常使用界面。

这项技能侧重于修复和实现，而不仅仅是评分。它与 audit（跨多个维度进行衡量）和 harden（广泛处理边缘情况）互为补充。当无障碍是首要目标时，请使用这项技能。

必须先完成的准备工作

用户通过 /a11y 启动此工作流。激活此技能后，加载 $frontend-design——其中包含设计原则、反模式和上下文收集协议。继续之前，必须遵循该协议——如果尚无设计上下文，必须先加载 $setup。

请参阅无障碍测试参考，了解自动化工具集成（axe、WAVE、Pa11y）和 CI 工作流指南。 当颜色承载状态、图表或验证信息的含义时，请参阅色觉缺陷 UX 参考。 有关键盘支持、焦点处理、跳过链接和隐藏内容模式，请参阅组件无障碍参考。 有关焦点、加载、过渡和反馈状态，请参阅交互设计参考。 检查颜色传达的是状态还是纯装饰时，请参阅语义颜色参考。 当无障碍需求需要适应小屏幕、触控场景或缩放级别时，请参阅响应式设计参考。

评估无障碍体验

找出问题所在及其影响对象：

1. 首先运行自动化检查：

   • 使用 axe-core、WAVE 或 Pa11y 检查关键页面
   • 以 WCAG 2.1 AA 为基准
   • 按严重程度记录违规项：严重（阻碍任务）、较重（难以绕过）、中等（令人困扰）、轻微（有待润色）
   • 将自动化结果视为快速预警机制，而非完整审计

2. 手动测试键盘导航：

   • 拔掉鼠标。你能访问每个交互元素吗？
   • Tab 键顺序是否合乎逻辑且可预测？
   • 焦点指示器是否清晰可见？
   • 是否存在键盘陷阱（无法通过 Tab 键离开的区域）？
   • 自定义组件是否能响应 Enter、Space、Escape 和方向键？

3. 使用屏幕阅读器测试：

   • 使用 NVDA（Windows）、VoiceOver（macOS/iOS）或 TalkBack（Android）
   • 按标题、地标和表单字段导航
   • 确认动态内容变化会被播报
   • 检查装饰性元素是否对辅助技术隐藏
   • 确认错误消息和状态更新会被朗读

4. 检查视觉无障碍体验：

   • 验证对比度：普通文本为 4.5:1，大号文本为 3:1，UI 组件为 3:1
   • 在 200% 和 400% 缩放级别下测试，确保无需水平滚动且内容不丢失
   • 模拟色觉缺陷（绿色盲、红色盲、蓝黄色盲）
   • 确保状态或含义不只通过颜色传达
   • 检查启用高对比度模式后文本是否仍然清晰可读

5. 检查动态效果和动画：

   • 启用 prefers-reduced-motion，确认界面仍然可用
   • 确保没有仅通过动态效果才能显示的关键信息
   • 确认自动播放的内容可以暂停或停止

按领域修复

语义化 HTML

为不同用途使用合适的元素。原生 HTML 元素自带无障碍支持。

修复：

• 将用作按钮的 <div> 或 <span> 替换为 <button> 元素
• 仅使用 <a> 进行导航，使用 <button> 执行操作
• 使用 <nav>、<main>、<aside>、<header>、<footer> 标记地标区域
• 使用 <ul> / <ol> 创建列表，而非设置样式的 div
• 使用 <table> 展示表格数据，而非 CSS 网格布局
• 使用 for 属性将 <label> 明确关联到输入框
• 使用 <fieldset> 和 <legend> 对相关表单项进行分组

应移除的反模式：

• 可点击的 div 缺少 role、tabindex 和键盘事件处理程序
• 仅用于调整字号的标题（<h1> 至 <h6> 应反映文档结构）
• 将占位文本用作标签
• 空链接，或只有图标且没有无障碍名称的按钮

键盘导航

所有交互元素都必须无需鼠标即可访问和操作。

修复：

• 确保所有交互元素都有 tabindex="0"（或本身可通过键盘聚焦）
• 移除应可聚焦元素上的 tabindex="-1"
• 移除正数 tabindex 值（它们会导致顺序不可预测）
• 为自定义组件实现键盘事件处理程序：
  • 按钮：按 Enter 和 Space 键激活
  • 切换控件：按 Enter 或 Space 键切换
  • 菜单：按 Enter 键打开，按 Escape 键关闭，使用箭头键导航
  • 模态框：按 Tab 键在框内循环，按 Escape 键关闭，关闭后将焦点返回触发控件
  • 手风琴：按 Enter 或 Space 键展开或收起，使用箭头键在各项之间移动
• 确保焦点清晰可见：提供明显的焦点环，不要在没有替代样式的情况下使用 outline: none 将其隐藏

焦点管理

焦点必须有明确目的、清晰可见且可预测。

修复：

• 在 SPA 中切换路由时，将焦点移至新页面的标题或主要内容
• 打开模态框时，将焦点限制在框内；关闭时将焦点返回触发控件
• 打开下拉菜单时，将焦点移至第一项
• 发生错误时，将焦点移至错误摘要或第一个无效字段
• 移除内容时，将焦点移至逻辑上合适的剩余元素（而非 document.body）
• 除非用户明确发起操作，否则不要在页面加载时自动聚焦字段

ARIA

仅在原生 HTML 无法满足需求时使用 ARIA。ARIA 不会改变行为，只会改变语义。

何时使用 ARIA：

• 没有原生 HTML 对应元素的自定义组件（标签页、树视图、复杂菜单）
• 需要显式角色的地标区域
• 用于播报动态内容的实时区域
• 无法通过可见文本提供的无障碍名称或说明

常见的 ARIA 修复：

• 为模态框添加 role="dialog" 和 aria-modal="true"
• 为展开控件按钮和手风琴触发控件添加 aria-expanded
• 为当前激活的导航项添加 aria-current="page"
• 为状态容器添加 aria-live="polite" 或 aria-live="assertive"
• 为图标和仅含图标的按钮添加 aria-label 或 aria-labelledby
• 为带有辅助文本或错误消息的输入框添加 aria-describedby
• 为无效表单字段添加 aria-invalid="true"

ARIA 反模式：

• 不要为实际的 <button> 元素添加 role="button"
• 不要在可聚焦元素上使用 aria-hidden="true"
• 不要使用相互冲突的角色（例如，在链接上使用 role="button"）
• 不要将交互元素嵌套在其他交互元素中
• 不要只依赖 ARIA，而不实现相应的键盘行为

颜色与对比度

确保无论视觉能力如何，信息都清晰可辨。

修复：

• 达到 WCAG AA 对比度：普通文本为 4.5:1，大号文本和 UI 组件为 3:1
• 绝不要仅依赖颜色表示状态、错误或必填提示
• 将语义颜色与文本标签、图标或形状差异搭配使用
• 在色觉模拟下检查语义颜色梯度
• 确保焦点指示器与背景之间有足够的对比度
• 为彩色状态指示器搭配清晰可见的文本标签或图标

屏幕阅读器支持

确保辅助技术用户获得同等信息。

修复：

• 为信息性图片提供描述性替代文本；装饰性图片使用空替代文本
• 对动态更新（搜索结果、表单提交、通知）使用 aria-live 区域
• 通过 aria-describedby 将表单错误与对应字段关联
• 为所有图标、按钮和控件提供无障碍名称
• 按层级使用标题（不要跳过级别）
• 为装饰性 SVG 添加 aria-hidden="true"，或使用带标题的 role="img"
• 确保表格使用恰当的 th 表头和 scope 属性

动效与动画

尊重无法忍受或不希望看到动效的用户。

修复：

• 将动画放在 @media (prefers-reduced-motion: no-preference) 中，或提供减少动效的替代方案
• 对于 prefers-reduced-motion: reduce，将动效替换为即时状态变化或轻微淡入淡出
• 不要在没有暂停／停止控件的情况下自动播放视频或动画
• 确保视差和滚动触发效果不会导致方向感错乱
• 在轮播、幻灯片和引导教程中尊重用户的动效偏好

验证改进

修复后，请验证这些改动是否有效：

• 重新运行自动化检查：确认之前的问题已解决，且没有引入新问题
• 键盘检查：再次通过 Tab 键访问每个交互元素
• 屏幕阅读器检查：通过标题、地标和表单字段进行导航
• 缩放测试：确认在 200% 和 400% 缩放时仍可正常使用
• 色觉模拟：确认状态和图表仍易于区分
• 减少动效：启用 prefers-reduced-motion，并确认界面仍可使用
• 真实设备：尽可能在实际辅助技术上进行测试

实用检查清单

• 所有交互元素都可通过键盘访问
• 焦点顺序合乎逻辑且可预测
• 焦点指示器清晰可见
• 尽可能使用原生 HTML 元素
• 仅在 HTML 无法满足需求时使用 ARIA
• 自定义组件具有恰当的键盘处理程序
• 颜色对比度符合 WCAG AA（文本为 4.5:1）
• 颜色不是表示状态或含义的唯一信号
• 图片具有描述性替代文本（并标明装饰性图片）
• 表单输入框具有关联的标签
• 表单错误与字段关联，并会被读出
• 动态内容变化使用 aria-live 区域
• 触控目标至少为 44 x 44 像素
• 界面在 200% 缩放时仍可使用
• 动效遵循 prefers-reduced-motion
• 自动化测试通过，且没有 WCAG AA 违规项
• 手动键盘和屏幕阅读器测试通过

切勿：

• 仅依赖自动化测试
• 使用 ARIA，却不实现相应的键盘行为
• 仅依赖颜色传达重要信息
• 移除焦点指示器，却不提供替代方案
• 对关键流程跳过使用真实辅助技术进行的手动测试
• 将无障碍访问视为一次性修复，而非持续实践

请记住：无障碍设计就是易用的设计。修复无障碍问题通常能改善所有人的使用体验。