Community程式設計與開發github.com

visual-qa

對於任何重大的 UI 變更,必須使用截圖驅動的視覺 QA 循環——用 Playwright 執行網站、擷取每個斷點、判斷每張截圖、修正、重複。在建立或重新設計任何頁面或區段後,以及在回報 UI 工作完成前使用。若需設計判斷,請使用 premium-frontend;若需轉換審計,請使用 conversion-optimization。

visual-qa 是什麼?

visual-qa 是一個為 AI 代理(如 Claude Code、Cursor)設計的工具技能,專注於透過結構化截圖 QA 循環確保 UI 品質。其核心前提是:有效的 JSX 不等於良好的設計,因此它強制開發者在回報 UI 工作前,先以視覺方式檢查每個頁面。此技能支援多種斷點(375px 至 1920px),利用 Playwright 自動擷取全頁截圖,並檢查水平溢出及主控台錯誤。它提供詳細的審查清單,涵蓋佈局中斷、層次結構、間距、印刷及 CTA 突顯度等問題,並特別針對行動裝置進行優化,檢查水平捲動、文字大小及點擊目標。工作流程強調迭代紀律:修正後重新擷取,直到所有斷點都沒有重大發現為止。它整合了 npm 指令進行自動化截圖,並建議使用瀏覽器開發者工具進行快速互動測試。此技能對於維護高品質 UI、防止通用 AI 設計模式,並確保每個螢幕尺寸都能提供良好的使用者體驗至關重要。

相容平台~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 工作已完成。

核心

在本地執行網站。

檢查:
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、廣告及訊息連結到訪。行動裝置是主要使用介面,而非事後補救。

  • 在 375px 寬度下沒有水平捲動;
  • 英雄文字不能過大——不能佔滿整個第一屏;
  • 點擊目標夠大,沒有任何東西太小;
  • 導航可開啟且可關閉;
  • 圖片是為直式裁切,而不是從橫式桌機裁切壓縮而來;
  • 黏性 CTA 存在且經過打磨。

循環紀律

  • 修正發現,然後重新擷取。不要盲目修正。
  • 直到完整掃描後沒有重大發現時才停止,而不是當清單變得無聊時。
  • 如果同一個發現修正後又出現,問題出在該區塊本身,而非頁面——請在區塊元件庫中修正。
  • 誠實回報:如果某個斷點仍有未解決的問題,請明確說出來。

Individual skills in this repo

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

相關技能