SuperAPI AI 工具集

accessibility

前端与建站

查看项目

更新于 10-27 16:56

技能介绍

用途

这是一个面向 Web 界面的无障碍(accessibility)审查技能,以 W3C 无障碍倡议(WAI)为依据。目标标准是 WCAG 2.2,符合级别为 AA——这也是 EN 301 549、ADA、Section 508 和欧洲无障碍法案背后的技术门槛。它把无障碍当作正确性要求,而不是一个功能,也不是事后补做的一遍。除非产品负责人设定了更高标准,否则以 WCAG 2.2 AA 为准。

主要能力

技能以 WCAG 的四大原则(POUR)组织:可感知(Perceivable)、可操作(Operable)、可理解(Understandable)、健壮(Robust)。它提供三种使用模式:

  • 生成(Generate):构建组件或页面时,优先使用原生元素,为每个控件提供可访问名称,确认键盘路径与可见焦点指示,运行 axe 检查,并用规则集作为清单逐项修复。
  • 审查(Review):针对拉取请求或 diff 运行规则集,每个失败写一条发现,按必须修复、可考虑排序;若无失败则一行说明,不编造发现。
  • 审计(Audit):对现有界面运行自动化检查(axe-core,约能捕获 30% 到 40%),仅用键盘走查关键路径,用屏幕阅读器(Chrome 配 NVDA 或 JAWS,Safari 配 VoiceOver)走查关键流程,并把每条发现映射到 WCAG 2.2 AA 准则。

技能建议优先排查真实站点中最常见的失败,顺序为:低对比度文本、缺失图片 alt、链接和按钮无可访问名称、未标注的表单字段、缺失 lang。

使用方式

输出格式为每行一条发现:<severity> · <topic> · <file>:<line> — <what is wrong>. <the fix as an action>. [WCAG <criterion>]。其中 severity 为 must-fix(违反 WCAG 2.2 AA 准则或阻断用户)或 consider(低于 AA 线的真实障碍或健壮性风险);topic 为规则集主题标识;WCAG 准则为可选。

所有模式都遵循 ARIA 五条规则的第一条:如果原生元素已经带有角色、状态、键盘行为和焦点,就使用它;没有 ARIA 胜过错误的 ARIA。

规则集概览

  • structure(结构):交互元素使用原生 <button> / <a href> / <input>,而非带处理器的 <div>;每页一个 <h1>,标题逐级下降;用 landmark 包裹区域,仅一个 <main>;列表用列表标记,表格数据用 <table> 配 <th> 和 scope;<html> 上设置 lang,每页有唯一描述性 <title>;新标签页或下载链接需说明;帮助机制在各页同一位置。
  • names-aria(名称与 ARIA):每个交互元素都有可访问名称,含纯图标按钮;链接和按钮文本单独读也有意义;不覆盖原生角色,ARIA 状态与 UI 同步;自定义组件遵循 ARIA APG 模式;模态框用 role="dialog" 或 <dialog> + showModal(),配 aria-modal="true" 和 aria-labelledby,Esc 关闭,背景 inert;aria-hidden 子树内不得有可聚焦元素。
  • keyboard-focus(键盘与焦点):每个交互元素仅用键盘即可到达和操作,无焦点陷阱;Tab 顺序遵循阅读顺序,无正 tabindex,DOM 顺序与视觉顺序一致;每个手势和拖放都有单指针替代;时间限制到期前警告且可延长或关闭;可见焦点指示用 :focus-visible,对比度 3:1;粘性页眉页脚不遮挡聚焦元素;"跳到主内容"链接是第一个可聚焦元素;客户端路由切换将焦点移到新视图;复合组件用 roving tabindex 或 aria-activedescendant;交互目标至少 24×24 CSS px 或有 24 px 间距。
  • forms(表单):每个字段有程序关联的 <label>,占位符不作标签;相关字段用 <fieldset> + <legend> 分组;错误用文本说明、aria-describedby 关联、aria-invalid 标记并给出修复建议,不单靠颜色;提交失败在表单顶部渲染错误摘要并移动焦点;不用禁用提交按钮表示表单无效;必填字段在可见标签和 aria-required 中说明;身份和联系字段设置 autocomplete;登录允许粘贴和密码管理器;有法律、财务或破坏性后果的提交可撤销、检查或确认。
  • perceivable(可感知):有意义的图片有传达信息的 alt,装饰性图片 alt="";视频有字幕,音频有文字稿,自动播放超 3 秒的音频有暂停/停止控件和独立音量;含义不单靠颜色、形状或位置;正文对比度至少 4.5:1,大文本、UI 组件边界和焦点指示至少 3:1;200% 缩放可用,重排到 320 CSS px 不丢失内容或功能;尊重 prefers-reduced-motion,无每秒超过三次闪烁;移动、滚动或自动更新超 5 秒的内容有暂停/停止/隐藏控件;强制颜色模式可用;悬停或聚焦显示的内容可关闭、可悬停、保持到关闭。
  • live-regions(实时区域):异步结果通过实时区域播报,role="status" / aria-live="polite",错误用 role="alert";实时区域元素在更新前已存在于 DOM;assertive/alert 仅用于真实错误;客户端导航更新 <title> 并移动焦点;加载状态用文本播报,完成也播报。
  • testing(测试):CI 中运行 axe-core 及对应框架的 lint 插件(React 用 eslint-plugin-jsx-a11y,Angular 用 angular-eslint 模板无障碍规则,Vue 用 eslint-plugin-vuejs-accessibility),约能捕获三分之一;仅用键盘走查关键路径;用屏幕阅读器走查关键流程;在 400% 浏览器缩放和增大系统文字下测试;单元测试按角色和可访问名称查询;对比度在设计系统中检查一次;自定义组件基于可访问原语(Radix、React Aria、Angular CDK)构建。

适用场景

适用于构建或评审 Web UI 时的无障碍检查,包括生成组件、审查代码 diff、审计现有界面。技能与 architecture-and-design、react、angular、vue、styling-and-design-tokens、i18n-and-localization 等技能组合使用:本技能决定无障碍要求,框架技能决定满足要求的 API。

限制

本技能覆盖 Web UI 的无障碍,不覆盖:ATAG(创作工具)或 UAAG(浏览器);原生移动无障碍(iOS UIAccessibility、Android 无障碍 API)和文档无障碍(PDF、Office);法律建议;超出 AA 的 WCAG AAA 准则,以及进行中的 WCAG 3 和认知无障碍(COGA)工作;满足感知要求的 CSS;从 locale 设置 lang 和 dir 及隔离双向文本;每条规则背后的框架机制。

参考资料

规范性资料:WCAG 2.2(w3.org/TR/WCAG22)、WAI-ARIA 1.2 与 ARIA Authoring Practices Guide(w3.org/WAI/ARIA/apg)、Using ARIA 五条规则(w3.org/TR/using-aria)、ARIA in HTML(w3.org/TR/html-aria)。实践者资料:MDN Accessibility、The A11Y Project checklist(a11yproject.com/checklist)、WebAIM、GOV.UK Design System。冲突时,本技能决定无障碍要求,框架技能决定满足要求的 API。