ss-a11y

在执行此工作流前，请先按照 更新前检查 的说明，每个会话执行一次。

无障碍审计

以注册表为先的制品边界

如果 .styleseed/project.json 和 .styleseed/artifacts/index.json 存在，请先解析请求的制品 ID，然后只读取 .styleseed/bundles/<artifact-id>.md 和 .styleseed/manifests/<artifact-id>.json。对于注册表项目，绝不要回退到全局旧版 bundle。仅当不存在注册表时，旧版项目才可以使用 .styleseed/effective-rules.md。

不适用情形

• 对设计系统进行常规合规性审查 → 使用 /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. 可操作

• 触控目标：触控界面的最小尺寸为 44x44px（min-h-11 min-w-11）
  • 标记尺寸不足的触控点击区域；不要仅因经批准的指针优先型桌面控件高度为 36–40px 就将其标记
  • 指针优先型控件遵循已解析的契约；应保留键盘访问能力，并满足适用的无障碍最低要求
  • 图标按钮需要具有适合输入模式的明确点击区域
• 键盘导航：所有交互元素都必须支持键盘访问
  • 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 UI 组件（它们会自动处理 ARIA）
• 角色：自定义交互元素需要正确的 role 属性

设计系统令牌参考

令牌	最低对比度	说明
--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. 需要人工审查：标记需要人工判断的项目