Storybook accessibility

Storybook accessibility 表示 Storybook 不只是组件展示，还明确引入 a11y audit 能力，通常是 @storybook/addon-a11y 或等价的 browser-backed Axe sweep。它关注 story-level 可访问性信号，例如对比度、ARIA 基础错误、表单语义和交互状态，而不是泛化的 Storybook 文档能力。

这个 Topic 的作用是把“有 Storybook”和“有可访问性检查”分开。只有当项目配置、脚本或快照能证明 a11y addon/axe 类检查进入组件评审链路时才使用；否则应只标记 Storybook component QA。这种拆分能避免后续 Agent 误以为所有 stories 都经过无障碍筛查（projects/proxy-broker.md、projects/codex-vibe-monitor.md）。

当项目在 Storybook config/package 中有 @storybook/addon-a11y，并且 stories 是组件评审或 CI 检查的一部分时使用。若仓库只有 Storybook docs、viewport、test-runner 或截图脚本，应使用 Storybook component QA，不要强行升级为 accessibility。

如果改动涉及表单、Dialog、Popover、Tooltip、焦点管理、颜色 token、错误提示、禁用态或键盘可达性，并且项目有 story-level a11y 工具，就应命中本 Topic。若没有 addon 证据，仍可要求人工 a11y 复核，但不能把 Topic 写成已具备自动门禁（projects/kaisoumail.md）。

• 把 a11y addon 当成第一层自动筛查，而不是完整无障碍验收；键盘旅程、屏幕阅读器和真实路由仍需要额外验证。
• 组件库或 shadcn/ui 操作台优先配 Storybook a11y，因为 Radix primitives、表单、Dialog、Popover、Tooltip 都容易产生状态组合问题。
• 将 accessibility gate 绑定到 story coverage；没有 story 的组件无法被 Storybook a11y 检查。
• CI 中跑 story build/test 时保留失败上下文和截图，避免只看到 “a11y failed” 而没有具体 story。
• a11y story 需要覆盖真实状态组合：空态、错误态、loading、长文本、禁用态、危险操作确认和移动视口。只给 happy path 组件加 addon，不能证明操作台或设备 UI 的可访问性（projects/flux-purr.md）。
• 如果项目同时使用 shadcn/ui/Radix，默认把 Dialog、Popover、Form、Select、Tooltip 作为高风险组件优先检查，因为它们最容易在 focus trap、label、aria-describedby 或 contrast 上出错（projects/proxy-broker.md）。

• projects/proxy-broker.md：web/.storybook/main.ts 引入 addon-a11y，且有 verify-stories/test-storybook。
• projects/kaisoumail.md：公开 Storybook surface 与 Cloudflare control plane 一起发布。
• projects/flux-purr.md：设备控制台在 Web 子项目内启用 a11y、docs、vitest。
• projects/codex-vibe-monitor.md：dashboard component stories 启用 addon-a11y 与 docs。
• skills/style-playbook/references/topics/shadcn-ui/TOPIC.md：说明 open-code 组件层为什么需要状态枚举和 a11y 早期筛查。
• skills/style-playbook/references/topics/storybook-component-qa/TOPIC.md：作为基底 Topic，记录 Storybook 的组件状态、截图和 interaction QA 职责。

• 没有 addon 证据却打这个 Topic，会污染候选报告和项目记忆。
• 只跑静态 typecheck 不跑 browser-backed story，会漏掉真实 CSS/contrast 问题。
• 把 a11y 通过等同于产品可访问，会漏掉页面级 focus management、routing 和 auth 状态。
• 把 addon 安装当作完成，会漏掉 stories 覆盖缺口。没有 story 的组件不会被检查，因此项目快照应同时记录 Storybook coverage 和 a11y gate 的范围（projects/codex-vibe-monitor.md）。
• 只在本地浏览器看一眼组件，不保存可复现 story 或截图，后续改动无法比较。应把关键状态写进 stories，并让 CI 或手动验证能回到同一入口（projects/proxy-broker.md）。

• projects/proxy-broker.md
• projects/kaisoumail.md
• projects/flux-purr.md
• projects/codex-vibe-monitor.md
• skills/style-playbook/references/topics/storybook-component-qa/TOPIC.md