Community编程与开发github.com

visual-qa

基于截图的强制视觉质量检查循环,适用于任何重大UI变更——使用Playwright运行网站、捕获每个断点截图、评估每张截图、修复、重复。在构建或重新设计任何页面或部分后、报告UI工作完成前使用。

visual-qa 是什么?

visual-qa 是一个强制性的视觉质量保证(QA)技能,旨在确保在报告任何 UI 工作完成之前,对网站的所有重大视觉变更进行严格审查。它通过 Playwright 自动化工具,在 375px、390px、768px、1440px 和 1920px 等多个关键断点处捕获全页截图,并指导开发者逐张审查布局、层次、间距、排版、对齐、图片裁剪和 CTA 突出性等视觉问题。该技能特别强调移动端优先原则,针对本地商家网站的用户习惯(如来自 Instagram、Google Maps 等渠道的访问),检查水平滚动、文本大小、触摸目标和粘性 CTA 等细节。它要求开发者遵循严格的循环纪律:发现并修复问题后重新截图,直到所有断点通过审查,诚实报告未解决的问题,并在问题重复出现时修改组件库而非单个页面。此技能适用于任何使用 Playwright 进行端到端测试的现代前端项目,通过运行 `QA_ROUTES` 环境变量指定的脚本即可开始工作。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/artem2167/website-factory/tree/HEAD/.claude/skills/visual-qa

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

visual-qa 是做什么的?

有效的 JSX 并非良好设计的证据。在看过 UI 之前,永远不要报告 UI 工作已完成。

核心

在本地运行网站。

检查以下断点:
375px
390px
768px
1440px
1920px

捕获截图。

审查每张截图,检查:

- 布局断裂
- 层次结构薄弱
- 间距过大
- 间距不足
- 丑陋的换行
- 图片裁剪不当
- 边距不一致
- 字体过大
- 字体过小
- CTA 突出性不足
- 对齐问题
- 通用的 AI 设计模式

修复发现的问题。

重复,直到没有重大视觉问题。

如何运行

启动开发服务器,然后执行:

QA_ROUTES=/,/services,/doctors,/contact node scripts/qa-screenshots.mjs

输出文件位于 qa/<route>/<width>.png,全页截图,每个断点一个文件。 该脚本还会报告每个断点的水平溢出和控制台错误——两者都会自动导致失败。

捕获的断点:375×812、390×844、430×932、768×1024、1440×900、1920×1080。

首次设置:

npm i -D playwright && npx playwright install chromium

如需交互式检查而非全面扫描,编辑器内的浏览器工具更快:打开页面,调整大小,阅读无障碍树,检查控制台。

阅读截图

逐个断点进行检查。针对每个断点回答以下问题:

  1. 是否有什么东西水平溢出?
  2. 是否有一个明显的焦点,还是视线会分散?
  3. 标题是否出现丑陋的孤行或单字行尾?
  4. 段落之间的边距在应该一致的地方是否一致,在应该故意不同的地方是否不同?
  5. 图片是否裁剪到了人脸、盘子或床?
  6. 主要 CTA 是否是其屏幕中最突出的元素?
  7. 在移动端上:粘性 CTA 是否可见、拇指可触及、并且没有遮挡内容?
  8. 任何东西看起来像默认的 AI 页面吗——渐变、图标卡片网格、药丸徽章、模糊斑点?

移动端专项检查

本地商家的用户从 Instagram、Google Maps、TikTok、广告和 Messenger 链接进入。移动端是主要界面,而非附加功能。

  • 在 375 宽度下无水平滚动;
  • 首屏文字不要过大——不能占满整个首屏;
  • 触摸目标足够大,没有微小元素;
  • 导航可访问且可关闭;
  • 图片按竖屏裁剪,而非从横屏桌面裁剪缩小;
  • 粘性 CTA 存在且精致。

循环纪律

  • 修复发现的问题,然后重新截图。不要盲目修复。
  • 当全面扫描没有发现重大问题时才停止,而不是因为列表变得无聊。
  • 如果修复后同一个问题再次出现,问题出在组件库而非页面——在组件库中修复它。
  • 诚实报告:如果某个断点仍有未解决问题,请说明。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相关技能