cometchat-a11y

事实依据： UI Kit 组件文档说明，这些组件的设计目标是达到 WCAG 2.1 AA 级，并内置了键盘导航（Angular 组件文档对此说明得最明确；请注意，文档本身也指出，仍需通过手动测试才能确认完全符合要求——不要在未进行此类测试的情况下，向用户笼统宣称已达到 AA 标准或拥有 VPAT）。应将 AA 视为设计目标，而非经过认证的保证。CometChat 应用中的无障碍问题几乎总是由宿主端回归问题导致的——全局 CSS、错误的焦点顺序、缺少无障碍名称的容器，或无视用户偏好的动画。请根据组件自身的文档页面（cometchat-<family>-components → docs-map）核实组件级无障碍声明；本技能负责处理套件无法控制的宿主端规范。

在以下情况下使用此技能

进行无障碍审查（WCAG / Section 508 / ADA / EN 301 549）、处理屏幕阅读器或键盘相关问题，或“让我们的聊天功能无障碍”时。公共部门、教育、医疗保健和大型企业的采购都需要考虑这一点。

从套件提供的功能开始

套件提供无障碍组件：可通过键盘操作的列表和消息编辑器、焦点处理，以及以达到 AA 为设计目标的语义结构（这是设计目标，并非经过认证的保证；见上文）。在 Web 上，套件会自行设置 ARIA 角色和名称——会话列表和用户列表会呈现为带标签的 listbox，并管理焦点轮转——因此不要覆盖或移除这些设置。你的职责是不要破坏现有功能，并确保周边应用同样无障碍。首先遵守以下两条规则：

1. 不要让全局 CSS 渗入 .cometchat 子树（Web）——全局 outline:none、低对比度覆盖、text-align/flex 重置，或 Tailwind 基础样式，都可能移除焦点环，或破坏套件已正确设置的对比度。请将重置样式的作用范围设在套件之外（RULES.md → CSS isolation）。
2. 为聊天容器提供真正且带标签的承载区域——设置有尺寸的区域（无障碍体验也需要可见且未折叠的界面），并提供无障碍名称（例如，在 Web 上使用 aria-label/landmark，在原生平台上使用无障碍标签），以便屏幕阅读器用户找到并进入该区域。

检查清单（宿主端）

• 键盘： 每条操作路径都能通过键盘访问和操作——打开会话、输入、发送、打开线程、关闭。不要锁住焦点；面板或对话框关闭时，应合理地将焦点移回。不要移除焦点轮廓；如果要重新设置样式，请保留可见的焦点指示器。
• 屏幕阅读器： 界面及其区域都应有无障碍名称；套件周围的自定义按钮应有标签（不能只有图标而没有 aria-label/无障碍标签）。新消息播报：请在目标屏幕阅读器（VoiceOver/NVDA/TalkBack）上验证套件的实时区域行为，并且不要通过祖先元素上的 aria-hidden 将其屏蔽。
• 对比度： 如果为套件设置主题（cometchat-<family>-customization），请确保文本/UI 对比度达到 AA 标准（普通文本为 4.5:1，大号文本/UI 为 3:1）。请同时检查浅色和深色主题——在浅色背景下通过检查的品牌色，在深色背景下可能不达标。
• 减少动态效果： 在聊天周围添加动画时，应遵循 prefers-reduced-motion（Web）/操作系统的“减少动态效果”设置（原生平台）；不要强制播放用户已选择关闭的动态效果。
• 文本缩放/缩放： 界面在 200% 缩放/大号 Dynamic Type 下仍须可用——不要限制字号，也不要在大号文本下裁切内容。
• RTL： 针对 RTL 语言环境调整文本方向（与 cometchat-i18n 配合使用）。
• 触控目标： 自定义控件应达到最小触控目标尺寸；不要缩小套件的控件。

通话无障碍（如果使用通话功能）

• 请求使用摄像头/麦克风时，应明确告知用户，并说明原因。
• 为你添加的通话控件（静音、挂断、摄像头）提供无障碍标签。
• 如果条件允许，应提供字幕/转录；确保来电界面会播报，且可通过键盘/辅助技术操作。

测试

• 自动化（Web）： 在聊天屏幕上运行 axe/Lighthouse，修复其标出的对比度、缺少名称和 ARIA 误用问题。（自动化工具只能发现约三分之一的问题；也要进行手动检查。）
• 手动： 拔掉鼠标，用键盘 Tab 键完成整个流程；使用 VoiceOver / NVDA / TalkBack 操作；将缩放调至 200%；切换减少动态效果；切换到深色主题。修复你自己的接线中出现的问题；如果确实是组件库组件的缺陷，请对照组件文档核实并报告（不要直接修改组件库内部代码）。

常见问题

1. 全局 CSS 清除了 .cometchat 内的焦点环或对比度样式——将重置样式限制在其他范围内。
2. 仅含图标且没有标签的自定义按钮——添加无障碍名称。
3. 未标注、已折叠或无法访问的聊天容器——为其设置尺寸并添加名称。
4. 动画未遵循减少动态效果的设置。
5. 只检查了一种主题下的对比度——检查浅色和深色主题。
6. 以为自动化工具就足够了——它们无法发现键盘和屏幕阅读器操作流程中的问题；请手动测试。

验证效果

聊天流程完全支持键盘操作，并显示焦点指示器 · 屏幕阅读器会播报界面、消息和控件 · 浅色和深色主题下的对比度均达到 AA 标准 · UI 在 200% 缩放/大号文字下正常显示 · 遵循减少动态效果的设置 · RTL 镜像显示正确 · 聊天屏幕通过 axe/Lighthouse 检查，没有对比度/名称/ARIA 错误。