SuperAPI AI Directory

accessibility

General & other

View repository

Updated 10-16 09:30

About this skill

Accessibility (Accessibility / A11y)

Reference sources:WCAG 2.2、The Accessible UI/UX Design Playbook 2026

Applicable scenarios

  • Government / education / public service products (compliance requirements)
  • Internationalized products (European and American markets)
  • Diverse user groups (elderly / visually impaired / hearing impaired)
  • Improve overall product quality

Core principles (WCAG POUR)

Perceivable(可感知)
  内容必须能被所有用户感知
  - 文本替代(图标 alt)
  - 字幕(视频)
  - 颜色不是唯一信息载体

Operable The interface must be operable by all users

  • Keyboard accessible
  • Enough time
  • Does not trigger seizures (avoid rapid flashing)
  • Easy to navigate

Understandable Content and operations must be understandable

  • Language identification
  • Predictable behavior
  • Input assistance

Robust Must be compatible with assistive technologies

  • Semantic HTML
  • ARIA attributes
  • Screen reader friendly

## WCAG 等级

```text
A  (最低):基本可访问性
AA (推荐):行业标准 ← 大部分产品的目标
AAA(最高):高级别要求

本 skill 默认 AA 级。

Core checklist

Visual

□ 文字对比度 ≥ 4.5:1(正文,AA 级)
□ 文字对比度 ≥ 3:1(大文字 18px+ 或 14px+ bold)
□ 非文字元素对比度 ≥ 3:1(图标、边框、按钮边)
□ 颜色不是唯一信息载体(错误状态除红色外加 ✗ 图标)
□ 文字可缩放至 200% 不破坏布局
□ 不依赖颜色区分链接(加下划线)

Keyboard

□ 所有可交互元素键盘可达(Tab 键)
□ Tab 顺序符合视觉顺序
□ 焦点状态明显(不是浏览器默认的 outline:none)
□ 没有键盘陷阱(能进去能出来)
□ 键盘快捷键可关闭/重映射
□ Skip Link(跳过导航直达内容)

Touch

□ 触控目标最小 44×44px
□ 相邻可点击元素间距 ≥ 8px
□ 不依赖手势(提供按钮替代)

Semantics and structure

□ 用语义 HTML(h1-h6/nav/main/article 而非 div)
□ 标题层级正确(不跳级)
□ 表单字段有 label
□ 图片有 alt(装饰图 alt="")
□ 图标有 aria-label 或文字
□ 动态内容用 aria-live 通知

Motion

□ 支持 prefers-reduced-motion 媒体查询
□ 没有快速闪烁(< 3 次/秒)
□ 自动播放可暂停
□ 视差滚动可关闭

Forms

□ 错误信息不只用颜色(加图标 + 文字)
□ 错误信息有 aria-describedby 关联
□ 必填字段明确标识
□ 提示文字(placeholder)不替代 label
□ 表单可被键盘完全填写和提交

Media

□ 视频有字幕
□ 音频有文字版本
□ 图表有数据替代(表格)

Focus Ring design

不要做:
  - 移除 outline(outline: none)
  - 用极淡的颜色

要做:
  - 焦点可见(蓝色 outline / 阴影)
  - 焦点宽度 ≥ 2px
  - 焦点对比度 ≥ 3:1
  - 提供 :focus-visible 区分键盘和鼠标

示例 CSS:
.button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

Common ARIA usages

aria-label="关闭"            # 图标按钮
aria-labelledby="title-id"   # 引用标题
aria-describedby="desc-id"   # 引用描述
aria-hidden="true"           # 装饰元素,屏幕阅读器跳过
aria-live="polite"           # 动态通知(不打断)
aria-live="assertive"        # 紧急通知(打断)
aria-expanded="true|false"   # 折叠状态
aria-controls="panel-id"     # 控制的元素
role="alert"                 # 警告
role="dialog"                # 对话框

Output format

## 可访问性检查:[页面/组件]

### WCAG 等级目标:AA

### 视觉
✅ 主文本对比度:6.2:1(黑#1a1a1a on 白)
✅ 副文本对比度:4.6:1
⚠️ 灰色 placeholder:3.2:1(达到 AA 大文字标准)

### 键盘
✅ 所有交互元素 Tab 可达
✅ 焦点环:2px 蓝色 outline
✅ 无键盘陷阱
✅ Skip Link 已设置

### 触控
✅ 按钮:48px × 48px
✅ 列表项:56px 高
✅ 间距:12px

### 语义
✅ 使用 nav/main/article
✅ 标题层级:h1 → h2 → h3
✅ 所有图标有 aria-label

### 动效
✅ 支持 prefers-reduced-motion
✅ 无快速闪烁

### 待修复
- ⚠️ 灰色 placeholder 对比度偏低,建议加深到 4.5:1
- ⚠️ 头像图片缺少 alt 属性

Workflow

1. 设计完成后做可访问性检查
2. 用核心检查清单逐项检查
3. 用工具验证(axe DevTools / WAVE)
4. 修复问题(按严重程度)
5. 输出可访问性报告
6. 转交前端实现

Recommended tools

设计阶段:
  - Stark(Figma 插件):对比度检查
  - Contrast Ratio Calculator

代码阶段:
  - axe DevTools(浏览器扩展)
  - WAVE(浏览器扩展)
  - Lighthouse(Chrome DevTools)
  - NVDA / VoiceOver(屏幕阅读器实测)

Quality self-check

□ 是否符合 WCAG 2.2 AA 级
□ 所有交互元素键盘可达
□ 焦点状态明显
□ 对比度满足要求
□ 颜色不是唯一信息
□ 表单有 label 和错误提示
□ 图标有文字替代
□ 支持 reduced-motion
□ 用工具实测过(不是只看清单)

Common pitfalls

  1. outline: none with no replacement——keyboard users lose focus feedback
  2. Expressing status with color alone——color-blind users cannot see errors
  3. Contrast just barely meets the standard——4.5:1 is still hard to read on some screens
  4. Using placeholder as a label——visually impaired users cannot find the field name
  5. aria-label translation errors——a Chinese product uses an English label
  6. Icon buttons have no label——screen readers cannot read pure icon buttons
  7. Touch targets too small——elderly people cannot accurately tap 24px buttons on mobile
  8. Not testing in practice——only reading the checklist without testing with a screen reader

Supporting templates

  • templates/a11y-checklist-template.md — Complete checklist template
  • templates/contrast-table-template.md — Contrast record table template
  • templates/aria-cheatsheet.md — ARIA quick reference

Collaboration with other skills

上游:
  page-structure → 列出所有需要检查的元素

平行:
  component-states → Focus 状态
  design-tokens → 对比度 tokens
  visual-style → 视觉风格不能违反对比度

下游:
  design-handoff → 可访问性要求交接给前端
  usability-evaluation → 可访问性是评审重点之一