experience-accessibility-validate

Web 组件无障碍

Web 组件的无障碍（a11y）模式和修复指南。每当涉及组件的可见或交互界面（如生成、修改、审查或设置 HTML、JS 或 CSS 样式）时，请参考本指南，以应用 WCAG 2.2 标准。

审查背景

请以提升 Web 无障碍为重点开展审查，并以 WCAG（Web 内容无障碍指南）为指导。

只有当代码与所引用的 WCAG 规则有直接关联，且明确违反相应标准时，才能将其标记为违规。

主要审查标准：

1. 仅关注无障碍：

• 仅评估组件的无障碍情况。
• 只考虑是否符合所引用的 WCAG 成功标准，忽略可归因于其他标准的违规。
• 不要涉及通用代码风格、模式或与无障碍无关的问题。

2. 确保无障碍要求达到必要且充分的程度：

• 找出阻碍组件满足 WCAG 最低要求的无障碍问题。
• 除非确有必要，否则不要提出超出 WCAG 合规范围的改进建议。

3. WAI-ARIA 的使用：

• 仅在无法通过语义化 HTML 实现无障碍时，才使用 WAI-ARIA 属性。
• 避免因错误或过度使用 WAI-ARIA 属性而引入不必要的复杂性或潜在回归。

4. 组件库的使用

• 假设常见的组件库（例如 Salesforce Lightning、Material UI、Chakra UI）在正确实现后即可直接使用。除非组件库中的组件被用于违反 WCAG 的情形，否则本次审查可以忽略这些组件，因为它们在抽象层下以无障碍方式实现。
• Lightning 基础组件（lightning-input、lightning-combobox、lightning-textarea、lightning-icon 等组件）通过 label 和 alternative-text 等专用属性提供无障碍标签、ARIA 和错误处理。即使使用 variant="label-hidden"，label 在程序上仍然有效；不要要求使用同级或包装 <label> 来关联该组件。导航、图标按钮及其他自带标签的基础组件同样会将提供的标签文本作为其无障碍名称，并将内部图标视为装饰性内容。不要仅仅因为实现细节隐藏在组件内部，就报告缺少关联。
• 同样的自带标签规则适用于任何框架中的导入组件或自定义控件组件（React/JSX、Angular、Vue、Web Components），而不仅限于 Lightning。大写或导入的组件标签（<Input>、<TextField>、<Button>、<Select>、<Checkbox>、<SearchField>，以及 Material UI、Chakra、Radix 或内部库中的设计系统包装组件）不是原生 HTML 元素——假设它们在抽象层下会自行渲染无障碍标签、ARIA 和错误处理（参见组件库依据规则）。此类组件若带有标签属性——label、aria-label、aria-labelledby、title 或可见的子文本/children——则视为已通过程序方式添加标签，不要因缺少 <label>、缺少 for/id 关联或缺少无障碍名称而标记。只有在没有提供任何标签属性或文本，或提供的值明显为空或不合理时，才标记问题。对于无法查看其内部控件的组件，不要要求原生的 <label for>。
• 在判断标签关联前，先解析动态的 id / htmlFor / for 表达式。当 <label htmlFor={X}>（或 for={X}）与控件的 id={X} 绑定到同一表达式（同一变量、属性、useId() 值或模板字符串，例如 htmlFor 和 id 都设为同一个插值 ${id}-email）时，即使审查时无法解析出具体字符串，也应视为关联匹配。只有在能明确证明两个表达式不同时，动态 id/htmlFor 才算不匹配。不要将完全相同的动态 id/htmlFor 表达式标记为未关联或标签不匹配。

5. 源码解读

• 在判断表达式之前，先根据框架的绑定语义解析表达式。追踪动态值在当前上下文中的所有可用来源。在 React/JSX 中，表达式可能引用局部变量、属性、Hook 结果或导入的绑定；Vue、Svelte 和 Astro 各自有模板或脚本作用域。特别是在 LWC 模板中，{someValue} 会解析为组件类（.js 或 .ts）中的字段、属性或 getter，包括 @api 属性；不能直接绑定模块级导入常量。在 Aura 标记中，应沿着值提供者（例如 v. 或 c.）追踪到对应的组件属性或控制器逻辑。检查适用的源码之前，不要断定某个值未定义、为空或缺失。在差异内容中，确认修正后的代码位于哪一侧，不要想当然地认为改动引入了问题。

重点：提供可执行的反馈，确保组件符合必要的 WCAG 无障碍要求，避免提出与提示范围无关的多余反馈。只有在代码中存在可立即修复的问题时才指出。你必须进行审查，并随后给出能够解决该问题的代码修复建议。

成功标准评审员

确定哪些成功标准适用于正在评审的代码，然后打开与该代码相关的参考文件。每份参考文件都提供针对特定标准的分析、示例和修复建议；上述评审通用规则仍然适用。

可感知

• SC 1.1.1 非文本内容
• SC 1.3.1 (i) 列表
• SC 1.3.1 (ii) 表格
• SC 1.3.1 (iii) 表单标签
• SC 1.3.1 (iv) 区域
• SC 1.3.1 (v) 组
• SC 1.3.5 识别输入目的
• SC 1.4.3 对比度（最低）

可操作

• SC 2.1.1 键盘
• SC 2.4.4 链接用途
• SC 2.4.6 标题和标签
• SC 2.5.1 指针手势
• SC 2.5.2 指针取消
• SC 2.5.3 名称中的标签
• SC 2.5.7 拖动操作

可理解

• SC 3.2.1 获得焦点时
• SC 3.2.2 输入时
• SC 3.3.1 错误识别
• SC 3.3.2 标签或说明
• SC 3.3.3 错误建议

稳健

• SC 4.1.2 (i) 名称
• SC 4.1.2 (ii) 角色
• SC 4.1.2 (iii) 值

视觉辅助评审

当组件截图或设计稿可用时，请使用以下视觉层面评审员补充源代码评审。每份参考文件都介绍了如何通过图像评估相应成功标准——包括对比度、颜色依赖、缩放/重排行为，以及从像素而非 DOM 中识别非文本内容。

• SC 1.1.1 非文本内容（视觉）
• SC 1.4.1 颜色的使用（视觉）
• SC 1.4.3 对比度（视觉）
• SC 1.4.10 重排（视觉）
• SC 1.4.11 非文本对比度（视觉）

评审输出

对于评估的每项成功标准，请报告发现的违规项。如果某项标准没有违规项，请为该标准返回空列表。