ui-a11y

无障碍审计

适用场景

需要审计组件或页面的无障碍问题并修复时，使用此技能。

不适用场景

• 一般设计系统合规性审查 → 使用 /ss-review
• Nielsen UX 启发式评估 → 使用 /ss-audit
• 非 StyleSeed 代码（没有 data-slot、没有语义令牌）——此技能假设遵循 StyleSeed 规范
• 运行时测试——这是静态代码审计，不是屏幕阅读器模拟

目标：$ARGUMENTS

审计标准

WCAG 2.2 AA 合规性

1. 可感知

• 颜色对比度：文本必须达到 4.5:1（普通文本）或 3:1（大号／粗体文本）
  • 检查 text-muted-foreground (#717182) 在 bg-background (#FFFFFF) 上的对比度 = 4.6:1（通过）
  • 检查白色背景上的 text-brand（使用你的皮肤主题品牌色验证对比度）
  • 标记任何不符合比例要求的自定义颜色
• 非文本对比度：UI 控件／图形必须达到 3:1
• 文本替代内容：所有 <img> 都需要 alt，有意义的图标需要 aria-label
• 不单靠颜色传达信息：不要只通过颜色传达信息（添加图标／文本）

2. 可操作

• 指针目标：WCAG 2.2 AA SC 2.5.8 要求尺寸为 24x24 CSS 像素，或满足适用的间距／其他例外情形。36px 的按钮不一定不合格。
  • 建议使用 44x44px（min-h-11 min-w-11）作为易用性目标；SC 2.5.5 在 AAA 级别要求此尺寸，并设有例外情形。
  • 检查实际可点击区域及相邻目标，而不只是图标的视觉尺寸。参见 最小尺寸 和 增强尺寸 标准。
• 键盘导航：所有交互元素都必须支持键盘操作
  • Tab 顺序应符合逻辑
  • focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2
• 动画：动画必须遵循 prefers-reduced-motion

  @media (prefers-reduced-motion: reduce) {
    *, *::before, *::after {
      animation-duration: 0.01ms !important;
      transition-duration: 0.01ms !important;
    }
  }
  

3. 可理解

• 标签：表单输入项必须有可见标签或 aria-label
• 错误消息：表单错误必须以编程方式关联（aria-describedby）
• 语言：<html lang="en">（或项目所用的适当语言代码）

4. 健壮

• 语义化 HTML：使用恰当的元素（<button>、<nav>、<main>、<header>）
• ARIA：Radix 原语可以提供无障碍行为，但组合使用时仍需验证名称、状态、焦点和键盘处理是否正确。
• 角色：优先使用原生控件；仅设置角色并不能实现键盘交互或无障碍状态。

设计系统令牌参考

令牌	最低对比度	说明
--foreground	7:1+	正文文本——请使用你的皮肤主题验证
--muted-foreground	4.5:1+	次要文本——请使用你的皮肤主题验证
--brand	4.5:1+	强调色——请使用你的皮肤主题品牌色验证
--destructive	4.5:1+	错误——请使用你的皮肤主题验证
--success	3:1+	仅适用于大号文本／图标——请使用你的皮肤主题验证
--warning	4.5:1+	警告文本——某些皮肤主题需要更深的变体

输出

1. 发现的问题：按严重程度（严重／主要／轻微）列出
2. 自动修复：尽可能直接应用修复
3. 需要人工审查：标记需要人工判断的项目

示例

用户请求：

审计组件或页面的无障碍问题并修复。

限制

• 仅当任务与其上游来源及本地项目上下文明确匹配时，才使用此技能。
• 应用更改前，验证命令、生成的代码、依赖项、凭据和外部服务行为。
• 不要将示例视为针对环境的测试、安全审查，或针对破坏性或高成本操作取得用户批准的替代方案。