accessibility

确保 Web 项目具备无障碍性并保持代码质量

从一开始就以无障碍性为目标构建 Web 项目至关重要，尤其是在人工测试有限的场景下（例如 AI 驱动的开发）。众所周知，事后再补充无障碍功能，成本和复杂度都远高于从一开始就正确实现。对任何开发任务都采用无障碍优先的方法，并详尽记录持续适用的要求。始终确保理解并正确落实本技能中未描述的无障碍标准。如果无法做到这一点，且你正在处理现有代码库，请谨慎提出重构尚不具备无障碍性的代码的建议。一旦发现缺陷，就必须立即启动这一流程；为此，需要了解并记录用户意图和应用限制。

代码注释和 WCAG 参考

积极添加代码注释，说明专为无障碍性而实现的功能，并根据任意级别的 WCAG 2.2 要求解释其依据。必要时，说明预期的用户操作流程。

使用语义化 HTML 和恰当的结构

首先，对所有内容和控件使用语义化 HTML。按钮使用真正的 <button> 元素，布局使用 <header>/<nav>/<main>，表单使用 <form> 和 <label>，标题使用逻辑清晰的标题层级。例如，<button> 元素默认支持键盘操作（可获得焦点，也可通过键盘激活），而 <div> 之类的非语义化元素则不具备这些功能。必须使用现有的原生元素，例如 <select>、<details> 或 <dialog>。如果无法避免使用自定义组件（通常确实无法避免），请遵循成熟的 ARIA 设计模式和键盘交互模型。只有在没有替代方案时才使用 ARIA，而大多数情况下都存在替代方案。如果确实使用了 ARIA，请记录这一选择及其原因。

确保页面的结构和地标清晰明了。使用 HTML5 分区元素划分导航、主要内容、表单等区域，让用户和你自己都能清楚了解内容的组织方式。始终为非文本媒体提供文本替代内容：为图像添加描述性替代文本，为音频/视频提供文字稿或字幕。如果你无法可靠地自行完成这些工作，请记录一项必须由其他维护者完成的阻塞任务。同样，对于数据表格，请使用表头（<th> 和 scope 属性）明确表格数据之间的关系，以便屏幕阅读器识别。避免使用“这里”“点击”或“继续阅读”之类的链接文本。如果这些文本在视觉上不可或缺，请提供其他获取其内容的方式（例如交互式卡片），并将这些文本从无障碍树中移除。

设计无障碍组件

每个组件的 HTML 结构都必须体现其语义：菜单或多选项控件使用列表，标题使用标题元素，一组表单字段使用字段集和图例等。保持焦点指示器（元素获得焦点时显示的轮廓或高亮）风格一致，以便键盘用户始终能看到焦点所在的位置。键盘无障碍不是可选项——确保用户仅通过键盘就能访问并操作每个交互元素（例如，按需使用 Tab、Enter、空格键和方向键）。这可能需要仅为自定义的可聚焦元素添加 tabindex，且只使用负值，并在脚本中处理自定义控件的按键事件。

请牢记 WCAG 关于触控目标尺寸的规则。所有内容都应易于访问。鼠标或手势操作（例如拖动）必须提供替代方式。

请使用无障碍检查工具和库。有些框架和组件库注重无障碍设计。如果使用 React/Vue/Angular，请利用其无障碍工具（例如 React 的 eslint-plugin-JSX-a11y），并优先选择经社区验证的无障碍组件。归根结底，无障碍组件需要结合正确的 HTML 结构、适当的 ARIA 角色和状态（在需要时），以及遵循辅助技术用户易用性惯例的脚本来实现。文档应记录每个自定义组件如何满足无障碍要求（例如，如何为图像组件提供替代文本，或轮播组件如何处理焦点和屏幕阅读器播报），以便扩展组件的任何人都清楚需要遵守哪些要求。

持续维护并避免反模式

实现无障碍不是一次性的工作——随着项目发展，需要持续评估。要长期保持最高水平的无障碍体验，每当添加内容或功能时，都应将无障碍检查作为持续要求。需要为未来的改动记录并落实以下几项关键实践：

• **为新增媒体提供替代文本：**每次添加图像或其他媒体时，都必须提供替代文本（或等效的文本替代内容）。可以将其列为拉取请求或内容发布工作流中的检查项。要求开发者或内容作者添加 alt 属性（或在适当情况下使用 alt="" 将图像标记为装饰性内容），以确保添加的每张图像都考虑到非视觉用户，即使内容由用户提供也是如此。对于图标，始终添加相应标签，并对纯视觉内容使用 aria-hidden="true"。替代文本应简短精炼，但没有字符数限制。

• **检查新增 UI 或样式改动的颜色对比度：**每当引入新颜色（用于文本、背景、图标、按钮等）或更改设计样式时，都要确认颜色对比度符合 WCAG 指南。根据 WCAG 2.x，_对比度_的计算公式为 (L1 + 0.05) / (L2 + 0.05)（其中 L1 是较亮颜色的亮度，L2 是较暗颜色的亮度）。该公式计算出的比值范围为 1:1（无对比度，例如白色背景上的白色文字）至 21:1（最高对比度，例如白色背景上的黑色文字）。普通文本与背景的对比度至少应为 4.5:1，而较大文本（大于约 18pt 或粗体约 14pt）至少需要 3:1。使用该公式或在线对比度检查工具计算任何新颜色组合的比值，并根据需要调整颜色或字号以达到标准。悬停、焦点、禁用等状态也适用此要求。

• **维护标题结构和地标：**添加新内容或页面时，确保标题层级（<h1>…<h6>）保持合理（不要随意跳过级别），并在适当情况下使用分区元素。例如，如果向页面添加新分区，可能需要设置正确级别的标题，并用 <section> 包裹，或将其添加到导航地标（<nav>、<main>、<aside> 等）中。

• **每次改动后重新评估：**随着应用不断扩展，持续重新测试其无障碍体验非常重要。将自动化测试（如 Pa11y）纳入回归测试套件，以便每次新构建都运行这些测试。

• **避免反模式：**用 <div> 实现按钮、使用 onclick 但未处理键盘操作、outline: none、用 aria-label 替代可见标签、在外部链接上使用 role=button 等。

后续待办事项

• <html> 需要 lang 属性（外语文本块也需要，但单个词不需要。如果项目支持多语言，请根据需要动态更改该属性）。
• 必须包含 <title> 元素。了解项目中这些元素的添加位置，并根据内容动态更改。
• 在每个非内容区块之前（例如导航之前）添加跳过链接，并且仅在获得焦点时显示。对于可能无关的大型内容组（>= 5），例如轮播，也要在其前添加跳过链接。链接名称采用“跳过‘内容’”的形式，例如“跳过导航”或“跳过赞助商链接”。确保结构变化后链接仍然正确。
• 在表单中，清楚地说明错误（不能只通过颜色表示）、要求以及组件状态。完全避免使用禁用状态。控件应改为不可见。
• 处理并遵循 prefers-reduced-motion。
• 视口尺寸或缩放级别发生变化时，应确保所有内容都能优雅地重新排布。
• 在项目组织和文档中清楚说明必须进行人工测试，并且设计师需要持续评估用户流程。
• 不要在 UI 本身提及无障碍体验。

设计注意事项

避免重复和／或过度使用设计模式，例如堆叠大量卡片、列表、导航、链接或按钮。保持布局和文本疏朗清晰至关重要。设计较长的表单时，应便于拆分为多个小步骤。不要在网站中堆砌交互元素，并应恰当地使用清晰、易于区分的图标。切勿将开发或工程要求设计成 UI 元素。

如果提示词可能导致无障碍缺陷

请告知用户，并解释该请求可能导致的问题，然后询问是否确实要继续实现。提出避免此类错误的建议；如果无法可靠判断，请撰写一份功能说明，交由另一位有残障的开发者自行评估。

无障碍知识

本技能并未涵盖以无障碍方式进行开发所需的全部知识。如果不确定，请务必说明，并仅参考 W3C/WCAG/WAI-ARIA 官方资源寻求帮助。