Agent Skills
返回列表
💻

Web无障碍质量保障

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/accessibility-skill-r60h。

技能介绍

无障碍为什么总是沦为事后补丁

在 AI 辅助前端开发中，人工测试时间往往被压缩，很多团队把无障碍检查推迟到上线前甚至发布后才补。这时再修复的成本远高于从零开始：语义化 HTML 的缺失意味着要重写组件结构，焦点管理混乱需要重构交互逻辑，对比度不足可能牵涉整个设计系统的色彩规范。

技能如何工作

这个技能把无障碍检查拆成几条可执行的硬约束，可以直接嵌入代码审查和组件开发流程。

语义化 HTML 优先

  • 用 <button> 而非 <div> 做按钮
  • 用原生 <nav> 做页面布局，<label> 和 <input> 做表单
  • 标题层级 <h1> → <h2> → <h3> 逻辑递进，不跳级
  • 优先使用原生元素：<a>、<button>、<input> 等

ARIA 标签规范

  • 只在没有原生替代方案时才使用 ARIA，并记录选择原因
  • 每个自定义组件文档化无障碍处理方式（alt text 策略、焦点管理、屏幕阅读器通知等）
  • 图标必须添加对应 label，视觉专用内容使用 aria-hidden="true"

键盘可访问性

  • 所有交互元素必须支持 Tab/Enter/Space/方向键操作
  • 触摸目标尺寸必须满足 WCAG 要求
  • 自定义焦点元素仅在必要时使用 tabindex，且只用负值

色彩对比度与非文本内容

  • WCAG 2.x 对比度公式：(L1 + 0.05) / (L2 + 0.05)
  • 普通文本最低 4.5:1，大文本 3:1，非文本 UI 组件 3:1
  • 所有图片提供描述性 alt 文本（装饰性图片用 alt=""）
  • 音频/视频提供字幕或文字稿

持续维护清单

  • 每次新增图片/媒体时检查 alt 文本，每次新增颜色时验证对比度
  • 使用 Pa11y 等工具集成自动化无障碍测试
  • 定期使用屏幕阅读器（NVDA/VoiceOver）手动测试
  • 表单错误清晰传达（不仅靠颜色），避免使用 disabled 状态

适用边界

  • 该技能主要面向 Web 项目，非 Web 环境（如 CLI 工具、原生移动应用）不适用
  • ARIA 不能替代语义化 HTML，滥用反而会破坏可访问性
  • 自动化测试只能覆盖部分问题，键盘和屏幕阅读器的手动测试仍是必需的
  • 需要结合团队自身的组件库和设计系统落地，不能机械照搬

使用场景

  • 构建面向公众的 Web 应用时，按语义化 HTML 和 ARIA 规范开发组件，确保符合 WCAG 2.2 AA。
  • 代码审查中发现按钮用 div 实现，依据反模式清单改为原生 button 并补充键盘事件处理。
  • 在 React/Vue 组件库中新增自定义控件，为焦点管理、角色和状态补充 ARIA 文档与代码注释。
  • AI 辅助生成前端页面后，运行持续维护清单检查图片 alt、对比度、标题层级和跳过链接。

适合人员

  • Web 前端工程师：需要在组件开发和代码审查中落实无障碍规范，减少上线后返工。
  • 设计系统维护者：负责统一按钮、表单、导航等组件的语义化和 ARIA 属性文档。
  • 无障碍测试工程师：使用 Pa11y、NVDA/VoiceOver 验证键盘操作、对比度和屏幕阅读器兼容。
  • 使用 AI 辅助开发的团队：希望在生成界面代码时注入无障碍约束，避免事后修复。