accessibility-inclusive-design

无障碍包容性设计

目的

帮助 Agent 设计和评审界面，让界面具备无障碍性、包容性、键盘友好性，并能兼顾屏幕阅读器，适用于不同人群。

使用此技能，将无障碍融入日常设计实践。将无障碍视为产品质量的一部分，而非后期 QA 任务或法律合规打勾项。

何时使用此技能

当用户寻求以下方面的帮助时，请使用此技能：

• UI、UX、前端实现、产品设计或设计系统工作。
• 无障碍评审、审计、修复、重新设计或一致性规划。
• 表单、导航、菜单、筛选器、产品列表、媒体、目录、动态加载或交互式小部件。
• 键盘交互、焦点管理、屏幕阅读器行为、语义化 HTML、ARIA、色彩对比度、排版、响应式行为或包容性内容。
• 为有视觉、听觉、运动、认知、语言、设备、带宽或情境限制的用户制定设计默认方案。

何时不使用此技能

请勿将此技能作为以下情况的主要技能：

• 与包容性或无障碍无关的广泛 UX 研究规划。
• 不涉及界面行为、内容或用户任务设计的纯品牌视觉探索。
• 不影响面向用户的无障碍体验的纯后端架构。
• 法律建议。你可以指出无障碍风险并建议依照标准进行审查，但不要作出法律认定。

核心原则

1. 为真实的多样性而设计，而非为“平均用户”而设计。 人们在能力、技术、语言、注意力、读写能力、设备、带宽和环境方面各不相同。避免只在设计者自身环境中有效的方案。
2. 从目的和用户任务出发。 明确目的可以降低复杂性和认知负荷，并减少实现浪费。
3. 优先使用原生语义和标准 Web 行为。 在用 JavaScript 和 ARIA 重新实现行为之前，先使用已包含角色、状态、键盘行为和平台集成能力的 HTML 元素。
4. 让结构可供机器读取。 标题、地标、列表、标签、表单控件、替代文本、字幕和文档元数据都是界面的一部分。
5. 渐进增强。 从有意义的内容和可用的 HTML 开始。只有在 CSS 和 JavaScript 能改善体验且不破坏基础体验时，才添加它们。
6. 让用户掌控体验。 在用户可以自行选择时，不要阻止缩放、锁住焦点、自动播放媒体、强制动效、采用无限滚动或替用户决定显示偏好。
7. 将惯例作为无障碍功能。 熟悉的导航、链接样式、按钮的可操作性提示、表单模式和可预测的位置，都能降低认知负担。
8. 明确呈现隐藏状态。 如果内容展开、加载、出错、被选中或发生动态变化，请通过视觉和程序化方式传达状态。
9. 内容也是设计的一部分。 清晰的标题、描述性链接、通俗易懂的语言、易用的标签和有帮助的错误提示，都是无障碍功能。
10. 测试范围要超越自动化。 自动化检查很有帮助，但键盘操作检查、屏幕阅读器检查、设备和浏览器测试，以及残障参与者的反馈，都能发现自动化测试遗漏的问题。

请参阅 references/principle-cards.md，了解每条原则的可复用卡片。

默认建议

除非用户提供了更明确的产品背景或限制，否则请采用以下默认建议。

领域	默认做法	通常这样做的原因	仅在以下情况覆盖默认做法
无障碍目标	按照 WCAG AA 级别的预期和当前产品／平台标准进行设计；将法律合规视为底线，而非目标。	上传的资料反复将无障碍视为内在品质，并指出 AA 是常见的合规目标。	用户有受监管的使用场景、内部标准或特定的合规目标。
产品目标	在布局或样式设计之前，明确用户的主要任务。	目的明确能简化决策并减少障碍。	用户只要求修复一个范围较小的组件。
语义	优先使用原生 HTML：button、a、label、input、fieldset、legend、nav、main、标题、列表。	原生元素自带预期的键盘操作和辅助技术行为。	所需交互没有合适的原生模式。
ARIA	仅在标记本身合理的基础上，使用 ARIA 补充缺失的名称、关系、实时更新和状态。	ARIA 会更改语义，但不会自动添加行为。	自定义组件确实需要 ARIA 角色／状态以及相匹配的键盘操作。
布局	使用灵活、由内容驱动且能自适应的布局；避免固定宽度／高度。	内容、设备尺寸、缩放比例和文本设置各不相同。	固定尺寸是媒体本身或受限平台界面的固有要求。
断点	根据内容出现问题的位置添加断点，而不是针对特定设备型号设置。	面向特定设备的断点无法涵盖所有使用场景。	原生应用或嵌入式界面有固定且已知的限制。
排版	使用易读的字体、相对单位、充足的行高、舒适的行宽和真实内容。	良好的可读性有助于弱视者、阅读障碍者、认知负担较重者、语言学习者以及其他所有人。	品牌字体受到限制；此时应测试并调整字号、间距、字重和对比度。
对比度	确保对比度充足，绝不单靠颜色传递信息；避免不必要的低对比度，也避免只提供刺眼的强光选项。	低对比度会排斥许多用户；过强的眩光会影响部分读者。	品牌调色板固定；此时应调整设计令牌，以满足对比度和舒适度要求。
链接	让行内链接在视觉上易于辨认，通常应加下划线；确保链接文本脱离上下文后仍有明确含义。	屏幕阅读器会单独列出链接；仅靠颜色区分的链接会让许多用户无法使用。	类似按钮的行动号召可以采用按钮样式，但仍需使用清晰的文本。
导航	使用带地标语义的列表式导航，放置位置应符合用户习惯，并清晰标示当前位置。	这种导航在视觉上、无 CSS 时以及辅助技术中都能正常使用。	极短的流程确实无需导航。
菜单	不要隐藏短菜单。对于展开式菜单，应使用真实按钮、可见标签、aria-expanded、相邻菜单和可靠的隐藏状态。	隐藏导航会增加操作成本和状态复杂度。	屏幕空间严重受限，或菜单内容很多。
表单	使用持久显示的标签；在适用时对控件分组；清晰标示必填项；提供宽容的验证方式和错误恢复机制。	表单很容易造成认知、操作和屏幕阅读器使用障碍。	极短的表单可能无需分组；但仍必须保留标签。
验证	优先在提交时进行验证；出现错误后，再在用户修正时提供有帮助的行内反馈。	过早进行实时验证可能造成干扰和压力。	字段的错误代价较高或涉及安全，且即时反馈明显有帮助。
密码	优先提供显示密码的控件，而不是强制用户重复输入密码。	这样能减轻认知和操作负担，同时让用户保有控制权。	安全策略禁止显示密码。
动态加载	优先采用明确的“加载更多”或由用户触发的更新，而不是无限滚动。应播报加载状态，并在新内容出现后移动焦点。	无限滚动会损害键盘导航、用户控制和方向感。	研究证明自动加载符合用户预期，并且提供了无障碍替代方案。
媒体	提供字幕、文字稿和有意义的图像替代文本。	不同用户需要不同的感官渠道和使用情境。	装饰性图像应使用空的 alt 文本，而不是描述文字。
动效	让动效可选、有明确目的且可控。	动效可能分散注意力、造成方向感混乱或引发不适症状。	动效传达必要状态；仍须提供减少动态效果的处理方式。
测试	至少进行纯键盘操作、焦点、语义／DOM、对比度、自适应／缩放和屏幕阅读器冒烟测试。	自动化无法验证真实的交互质量。	任务仅限概念设计；仍应说明上线前需要进行测试。

必须向用户询问的问题

不要要求用户批准常规最佳实践。采用默认做法并说明原因。

只有当答案会影响重要建议时，才提出一个聚焦的问题。如有可用的 question 工具或同等工具，请使用。

以下情况需要提问：

1. 合规是核心要求，但监管或组织目标尚不明确。
   • 默认：采用 WCAG AA 级设计和当前产品标准。
2. 受众、辅助技术、语言、地理位置或平台会对设计产生重大影响。
   • 默认：面向广泛的 Web 受众，支持键盘和屏幕阅读器，并适应浏览器的响应式行为。
3. 组件可能需要采用自定义交互模式，而非原生 HTML。
   • 默认：使用原生 HTML 或更简单的模式。
4. 品牌语气与清晰标签、通俗语言或易识别的操作提示相冲突。
   • 默认：优先使用清晰的任务描述，品牌个性居于次要位置。
5. 动态行为可能改变用户控制权、焦点或方向感。
   • 默认：采用由用户明确触发的操作，并提供视觉和程序化反馈。
6. 用户要求作出法律或符合性声明。
   • 默认：提供设计和实现建议，并建议由专家或法律专业人士进行验证。

请使用 references/decision-prompts.md 中可直接用于提问工具的提示词。

工作流

A. 评审现有 UI、截图、代码或流程

按以下顺序检查：

1. 任务与目的
   • 用户想要完成什么？
   • 主要操作路径是否清晰，是否已去除不必要的复杂性？
2. 结构与语义
   • 文档标题、语言、标题层级、地标、列表、控件、标签和关联关系是否有明确意义？
   • 源码顺序是否与阅读顺序和焦点顺序一致？
3. 键盘与焦点
   • 每个交互元素是否都能通过键盘访问、看到、操作和退出？
   • 焦点状态是否清晰可见，且未被移除？
   • 在展开内容、页内链接、验证和动态加载之后，焦点是否得到妥善管理？
4. 交互行为
   • 控件是否容易识别？
   • 状态和变化是否通过视觉和程序化方式传达？
   • 界面是否保留了用户的控制权？
5. 内容与标签
   • 标题、链接、表单标签、按钮名称、说明和错误信息脱离上下文后是否仍然清晰？
   • 品牌语言是否不会影响任务的清晰表达？
6. 视觉呈现
   • 对比度、文字大小、行高、行宽、间距和分组是否易于阅读？
   • 信息是否不只依靠颜色、位置或声音来传达？
7. 表单与错误
   • 标签是否始终可见并与相应控件关联？
   • 必填字段是否清晰标明？
   • 错误是否会被播报、显示在用户操作区域附近，并提供可执行的解决方法？
8. 媒体与替代内容
   • 图片、图标、视频、音频和非文本提示是否提供了适当的替代内容？
9. 响应式与环境适应能力
   • 在缩放、调整文字大小、窄或宽视口、网络较慢、禁用 CSS/JS，以及用户设置字体或颜色偏好时，是否仍能正常使用？
10. 测试与可维护性

• 无障碍检查是否已纳入组件或设计系统工作流？

评审结果应包含：

• 严重程度：阻断、重大、中等、轻微。
• 受影响人群：键盘用户、屏幕阅读器用户、低视力用户、认知负荷受影响者、运动能力受限者、语言或读写能力受限者、低带宽用户等。
• 为什么重要。
• 建议的修复方案。
• 实现说明。
• 验证测试。

B. 创建或改进设计

按以下顺序进行：

1. 明确功能和用户任务。
   • 如果信息缺失，请提出一个有针对性的问题，并给出默认方案。
2. 选择最简单且实用的模式。
   • 优先使用原生控件和熟悉的惯例。
3. 建立结构。
   • 在添加样式之前，定义标题、区域、阅读顺序、导航、表单分组和内容关系。
4. 编写标签和内容。
   • 使用直接、描述清晰且脱离上下文也能理解的文案。
5. 定义交互和状态。
   • 指定键盘行为、焦点顺序、可见焦点、状态播报、加载、错误和恢复方式。
6. 应用视觉设计。
   • 调整字体排版、对比度、间距、分组、可操作性提示和响应式行为。
7. 添加渐进式增强。
   • 仅在 HTML 基础版本可用后添加 JavaScript。
8. 验证边缘情况。
   • 测试缩放、长内容、本地化、相关时的 RTL、慢速网络、禁用 CSS/JS 的情况以及替代输入方式。
9. 解释决策。
   • 将建议与用户影响联系起来，而不只是引用标准。

决策框架

选择模式时，优先采用第一个能够满足用户任务的选项：

1. **无需交互：**使用语义化静态内容。
2. **存在原生交互：**使用原生元素。
3. **可以为原生交互添加样式：**保留原生行为，为标签或容器添加样式，而不是替换控件。
4. **渐进式增强足以满足需求：**保留基础表单/链接行为，并通过 JS 增强。
5. **无法避免自定义交互：**完整实现该模式：角色、名称、状态、键盘行为、焦点管理、可见的可操作性提示、说明和测试。
6. **该模式会隐藏内容或夺取控制权：**重新考虑。确认产品场景是否确实需要这样做。
7. **该模式依赖用户偏好：**提供选择，或遵循浏览器/操作系统设置。

实用规则

文档和页面结构

• 使用有效的 doctype。
• 使用 lang 声明页面语言；对于从右向左书写的语言，使用 dir 声明文本方向。
• 使用一个有意义的文档 <title>，标明当前页面或结果状态。
• 使用一个主要的 <main> 区域承载页面独有的内容。
• 为视力正常的键盘用户提供跳转至主要内容的链接。
• 使用标题来组织结构，而不是控制视觉大小。不要仅为实现某种样式而跳过标题级别。
• 使用列表组织导航和相关内容。
• 确保按源代码顺序从上到下阅读时，内容逻辑合理。

导航和方向指引

• 将主要导航放在 nav 地标中。
• 为多个导航地标设置不同的标签，例如“站点”和“目录”。
• 保持熟悉的位置和易识别的形状。
• 使用颜色之外的方式标示当前页面/章节。
• 对于指向当前页面的链接，避免多余的重新加载行为；适当时使用指向页面主要内容的同页链接，或清晰描述当前状态。
• 对于较长的页面，如果目的是在章节间导航，应使用目录，而不是复杂的下拉子菜单。

按钮、链接和控件

• 操作使用 button，导航使用 a href。
• 有原生元素可用时，不要使用可点击的 div 或 span。
• 不要移除按钮或链接的可操作性提示，除非能用同样清晰的提示替代。
• 仅图标控件需要无障碍名称。空间允许时，优先使用可见文本。
• 触控目标应足够大且彼此分开；在较窄的触控视口上，应使用占满整行的纵向导航。
• 不可见元素不得获得焦点。

键盘与焦点

• 所有可操作控件都必须能通过键盘访问。
• 每个获得焦点的控件都必须有清晰可见的焦点指示器。
• 除非提供更醒目的替代样式，否则不要设置 outline: none。
• 不要使用正数 tabindex 调整导航顺序，应改为修正源顺序。
• 仅对通过程序设置焦点的目标使用 tabindex="-1"，例如平滑滚动后的页内标题或新加载的内容。
• JavaScript 接管原生行为时，应恢复焦点移动、URL 更新和预期的键盘行为。

表单

• 每个输入项都必须有持久且相关联的标签。
• 占位符文本只能作为提示，绝不能将其作为唯一标签。
• 使用 fieldset 和 legend 来说明多个相关控件；如果没有益处、只会造成干扰，则应避免使用。
• 只询问完成任务所需的信息。
• 必填字段必须通过视觉和程序方式标明。
• 将错误信息放在靠近用户当前操作的位置，而不是只放在页面顶部。
• 将“存在错误”与“如何修正此字段”分开说明。
• 适当使用 aria-invalid 和 aria-describedby 标记无效字段并关联修正说明。
• 对异步表单或加载反馈使用实时区域，但不要对每次按键都反复播报。
• 对实时验证进行防抖处理，避免嘈杂、过于激进的验证。
• 除非政策不允许，否则优先使用“显示密码”，而不是重复输入密码的字段。

动态内容

• 对影响较大的更改，优先使用“应用筛选条件”和“加载更多”等明确操作。
• 向屏幕阅读器播报加载状态和完成状态。
• 请求待处理期间，应阻止重复触发加载操作。
• 新内容加载后，如果触发控件已被移走，应将焦点移至首个有意义的新项目。
• 默认应避免无限滚动。
• 如果使用实时区域，应根据紧急程度选择礼貌或强提示播报，并避免在非必要时打断常规阅读。

视觉设计与可读性

• 尽早使用真实内容，不要只用理想化的占位文本进行设计。
• 选择字体时，应考虑易读性、字符辨识度、语言支持以及所需的字重和样式。
• 使用相对单位设置文本、间距和布局。
• 保持适宜的行长，避免文本块过宽或过窄。
• 使用无单位的行高；除非排版测试支持其他值，正文行高通常约为 1.5。
• 除非断字和语言支持可靠且经过测试，否则避免在网页正文中使用两端对齐。
• 确保文本和 UI 状态有足够的对比度，但避免只采用不必要的强烈对比作为阅读方式。
• 通过形状、文本、图标、位置或图案传达状态，不要只依赖颜色。
• 利用留白和邻近关系明确分组。

媒体与非文本内容

• 装饰性图片使用空的 alt 文本。
• 信息性图片应使用简洁的 alt 文本说明其用途或内容。
• 链接图片应描述链接目标或操作，而不只是描述图片本身。
• 复杂图片、信息图和图表需要配套说明或结构化文本替代内容。
• 带语音的视频需要字幕和文字稿。
• 字幕应标明说话者变化和重要的非语音音频。
• 媒体播放器必须支持键盘操作、有清晰可见的焦点状态，并带有屏幕阅读器可识别的标签。

国际化与环境适应性

• 不要假定只有一种语言、地址格式、姓名格式、日期格式、设备、连接速度、指针类型或视口。
• 在可能存在国际差异的情况下，使用灵活的数据结构和 UI 标签。
• 测试较长的标签、译文、姓名、产品标题以及长度可变的内容。
• 面向 RTL 语言时，应支持 RTL 布局；优先使用可响应 dir 的布局系统。
• 不要限制浏览器缩放、文本缩放、用户字体选择或高对比度设置。
• 应将网页字体、图标和脚本视为增强功能，而非阅读或基本操作的必要条件。

无障碍与包容性要求

完成前，请核实：

• 无需使用鼠标即可操作产品。
• 焦点顺序符合视觉顺序和逻辑顺序。
• 焦点始终清晰可见。
• 交互元素具有无障碍名称、角色、状态和值。
• 重要内容不会仅隐藏在背景图片、伪元素、颜色、音频或布局位置中。
• 可以通过标题和地标导航页面结构。
• 借助辅助技术，可以理解、填写、纠正并提交表单。
• 错误、加载、展开/折叠、选中和无效状态都能通过视觉和程序方式传达。
• 在缩放、调整文本大小、小屏幕、用户字体设置和网络缓慢的情况下，文本仍然清晰可读。
• 提供媒体替代方案。
• 自动化检查应辅以手动键盘和辅助技术检查。

前端实现指南

• 先使用语义化 HTML，再添加 CSS，最后添加 JavaScript。
• 尽可能使用原生控件。应设置标签或包装元素的样式，而不是替换输入控件。
• 使用与语义状态关联的 CSS 属性选择器，例如 [aria-invalid="true"]、[aria-expanded="true"] 或 [aria-pressed="true"]，以减少状态与样式不一致的情况。
• 如果可以提供有效的表单/链接作为后备方案，就不要创建基本访问功能依赖 JavaScript 的控件。
• 如果组件隐藏内容，请确保隐藏的内容不在焦点顺序中。
• 如果组件显示内容，除非有充分理由，否则应按源代码顺序将显示的内容放在触发器附近。
• 如果组件异步更改页面内容，应提供实时区域反馈并妥善管理焦点。
• 使用设计令牌定义焦点、对比度、间距、禁用状态、错误状态和触控目标尺寸，将无障碍要求融入系统。
• 使用长文本、不同语言、缺失资源、禁用 CSS、脚本加载失败、高对比度模式、缩放和仅用键盘操作等情况测试组件。
• 对于设计系统，应为每个组件记录预期标记、键盘行为、ARIA 状态、焦点行为、内容规则和反模式。

质量检查清单

请使用 references/checklists.md 中的完整检查清单。至少在回答前确认：

• 建议从用户任务出发。
• 优先使用原生语义，而非自定义控件。
• 明确说明键盘和焦点行为。
• 在相关情况下，明确说明屏幕阅读器名称、状态和关系。
• 绝不将颜色作为唯一提示。
• 文本和标签脱离上下文后仍清晰易懂。
• 包含错误、加载和空状态。
• 考虑响应式布局、缩放和可变内容情况下的行为。
• 说明对用户的影响并提供测试步骤。

需要避免的常见错误

请参阅 references/anti-patterns.md 中的完整反模式列表。风险最高的错误包括：

• 可点击的 div 控件。
• 仅使用占位符作为标签。
• 移除焦点样式。
• 禁用缩放。
• 不必要地隐藏导航。
• 没有无障碍名称的纯图标控件。
• 仅通过颜色表示状态。
• 没有明确替代方案的无限滚动。
• 依赖 JavaScript 的静态内容。
• 视觉顺序与源代码/焦点顺序不一致。
• 用 ARIA 修补有缺陷的原生模式。
• 仅依赖自动化测试。

如何向用户解释建议

使用务实、关注用户影响的语言：

• “这不仅仅是为了合规；这样可以避免键盘和屏幕阅读器用户陷入困境。”
• “原生元素更简单、更可靠，因为浏览器已提供角色、键盘操作和平台集成。”
• “这个标签脱离上下文也需要有意义，因为屏幕阅读器可以单独列出控件和链接。”
• “视觉状态也需要有对应的程序化状态，以便辅助技术获取相同的信息。”
• “这种模式能保留用户的控制权；替代方案会导致界面行为出乎意料。”
• “默认方案能包容更多用户，也不会限制品牌表达。”

建议权衡方案时，请说明：

1. 默认方案，
2. 受到保护的用户群体，
3. 成本或限制，
4. 足以支持采用例外方案的条件，
5. 如何测试例外方案。