Ivan's Blog
主题

Storybook component QA

Storybook component QA 表示仓库把 Storybook 当作组件级文档、状态枚举、视觉检查或 interaction smoke 的稳定入口。它不等同于 Storybook accessibility：只有项目明确引入 a11y addon 或等价 Axe sweep 时，才同时打 accessibility Topic。这个拆分用于避免“只要有 Storybook 就叫 a11y”的误判。

  • 前端

目录

Definition

Storybook component QA 表示仓库把 Storybook 当作组件级文档、状态枚举、视觉检查或 interaction smoke 的稳定入口。它不等同于 Storybook accessibility：只有项目明确引入 a11y addon 或等价 Axe sweep 时，才同时打 accessibility Topic。这个拆分用于避免“只要有 Storybook 就叫 a11y”的误判。

这个 Topic 关注组件在应用上下文之外是否可复现、可审查、可截图和可交互。它适合作为 UI 改动的低成本证据入口，尤其在 shadcn/ui、设备控制台、ops dashboard 和嵌入式管理 UI 中，用 stories 固定复杂状态比临时浏览器点检更可靠（projects/proxy-broker.md、projects/dockrev.md）。

When to use

当项目有 .storybook/、storybook / build-storybook / test-storybook 脚本、story files，且这些 story 会影响 UI 评审、截图、docs 或组件交互验证时使用。若 Storybook 只是历史残留、没有脚本或 story surface，应先复核再标记。

如果改动会新增或改变 reusable component、form state、Dialog/Popover、dashboard card、设备控制面板、错误态、空态或视觉主题，并且 repo 有 Storybook 入口，应使用本 Topic。若只有应用级 e2e，没有组件级 story surface，则应记录为 Playwright/browser QA，而不是硬贴 Storybook（projects/blog-26.md）。

Habits / defaults

  • Storybook 先回答“组件状态是否可见、可复现、可截图”，再由 Playwright/e2e 回答完整用户旅程；projects/octo-rill.md 和 projects/proxy-broker.md 把两者分开。
  • 没有 a11y addon 证据时，默认只标记 component QA；projects/blog-26.md、projects/dockrev.md 都显式保留这个边界。
  • Storybook 端口和 daemon 脚本属于本地运行 contract；交给用户预览前仍要走全局端口租约，而不是直接复用项目默认端口。
  • 对于设备/ops UI，stories 应覆盖空态、错误态、长文本、深色/浅色主题、移动视口和危险操作确认，而不是只展示 happy path。
  • Storybook 与真实 app 的责任要分开：Storybook 用来稳定组件状态和视觉证据，Playwright/e2e 用来覆盖 route、auth、API、SSE 和真实数据流。两者互补，不能互相替代（projects/octo-rill.md）。
  • 当 stories 作为 PR 证据时，应保证入口可重复运行，并记录所用命令、端口租约或截图路径；否则 owner 只能看到一次性图片，无法复查组件状态（projects/dockrev.md）。

Reference implementations

  • projects/proxy-broker.md：Storybook、verify-stories、test-storybook、Playwright 共同构成 shadcn/ui 操作台 QA。
  • projects/dockrev.md：Storybook daemon 与 screenshot scripts 支撑运维 UI 的视觉证据。
  • projects/loadlynx.md / projects/isolappurr-usb-hub.md：设备 Web UI 用 Storybook 作为硬件之外的早期界面验证。
  • projects/codex-vibe-monitor.md：dashboard UI 使用 Storybook docs/a11y 记录组件状态，适合检查监控类界面的 loading、empty、historical data 和 SSE 状态。
  • projects/kaisoumail.md：Cloudflare control plane 的 Storybook surface 支撑表单型管理台的组件评审。

Failure modes

  • 把 Storybook presence 误命名为 accessibility，会让后续 Agent 误以为已有 Axe/contrast gate。
  • 只写 stories 不运行 story build/test，会让组件状态在 PR 中悄悄腐烂。
  • 把 Storybook 截图当成端到端证据，会漏掉路由、API、auth、real data 和硬件交互问题。
  • 只给组件 happy path 写 story，会让危险操作、错误恢复、长文本和权限状态无证据。改动面如果涉及这些状态，应先补 story，再截图或运行 test-storybook（projects/proxy-broker.md）。
  • 把 Storybook dev server 的默认端口直接交给用户，会和全局端口租约冲突；owner-facing 预览仍需要当前工作区持有的服务会话（projects/style-playbook-skills.md）。

Evidence index

  • projects/proxy-broker.md
  • projects/dockrev.md
  • projects/octo-rill.md
  • projects/blog-26.md
  • skills/style-playbook/references/data/topic-candidates.json
  • skills/style-playbook-write/scripts/catalog.py

相关内容