ux-audit

UX Audit

像真實使用者一樣親自走查線上 Web 應用程式。本審查以**互動優先（interaction-first）**為核心原則——包含打字、點擊、傳送、觀察與擷取畫面。單純的靜態 DOM 掃描無法產出任何有效裁定。

裁定狀態（Verdict states）

審查結果必須且僅能為以下四者之一：

• Pass（通過） — Critical = 0、High = 0，所有硬性門檻均為綠燈，且互動清單（Interaction Manifest）完整。
• Conditional Pass（有條件通過） — Critical = 0、High = 0，所有硬性門檻均為綠燈，但存在 Medium 或 Low 層級的問題。
• Fail（不通過） — 至少存在一項 Critical 或 High 層級的問題發現，或是硬性門檻出現紅燈。
• Incomplete（未完成） — 互動清單缺少必要項目、某個階段未執行，或是觸發了「審查再審查」的元檢驗（清單時間戳記間隔過近 < 0.5 秒、擷取畫面少於 2 × 路由數、Console 讀取少於 1 × 路由數，或是窮舉審查的 Phase 3 耗時少於 1 分鐘）。即使觀察到的畫面看起來無誤，也絕不能直接升級為 Pass。

如果審查工作未附上完整的互動清單，唯一合法的裁定只有 Incomplete。「看起來沒問題」不等於 Pass。若出具了缺乏合理時間間隔的 Pass 報告將會被駁回——Agent 必須重新執行帶有真實互動的審查。

硬性門檻（Hard gates）

以下項目一旦未達標，審查即自動判定失敗，且嚴禁降級處理。

門檻項目	門檻值	違規時的嚴重度
走查期間的 Console 錯誤	> 0	Critical
走查期間的 Console 警告	> 0	High
網路 5xx 錯誤	> 0	Critical
已驗證頁面出現網路 403 / 404 錯誤	> 0	High
在任何測試的視埠 / 面板組合下出現版面崩塌	> 0	High
任何受審頁面出現 axe-core Critical 違規	> 0	Critical
任何受審頁面出現 axe-core Serious 違規	> 0	High
代表性路由的 LCP（實用預算）	> 4.0s	High
代表性路由的 CLS	> 0.25	High
代表性路由的 INP	> 500ms	High
缺少必要的互動清單項目	不適用	Incomplete
清單項目間的中位數時間間隔 < 0.5 秒	不適用	Incomplete（未進行真實互動）

Console 警告的最低嚴重度為 High。5xx 錯誤自動列入 Critical。本 Skill 中不存在「Medium 層級的 Console 錯誤」——該類別根本不成立。

axe-core 門檻為按頁面執行（單一頁面出現 >1 個違規即判定失敗）。效能門檻則在代表性路由上執行一次（逐頁執行過於繁瑣）；實用預算標準遠高於「壞掉」的臨界點，又低於嚴格的 CWV 標準。完整的門檻與原理說明請參閱 references/performance-budget.md。完整的 a11y 配置與嚴重度對映請參閱 references/a11y-automation.md。

已知雜訊白名單（Allowlist for known noise）

某些應用程式包含已知的雜訊 Console / 網路類別，但這些並非真正的 Bug（例如 Sentry 資訊日誌、瀏覽器擴充功能干擾訊息、身分驗證檢查探針預期的 401）。請在 Phase 3 之前讀取 audit-config 檔案並套用白名單。路徑備用順序：.jez/audit-config.yml → audit-config.yml → .audit/config.yml。白名單內的項目仍會保留於互動清單中，但不會列入問題發現中。裁定區塊會同時顯示原始數量與列入白名單的數量：Console warnings: 3 (1 allowlisted, 2 reportable)。

未提供設定檔時的預設行為：每個 Console 錯誤 / 警告都會被視為一項問題發現。格式、語意與介面覆寫說明請參閱 references/audit-config.md。

執行階段（依序）

1. Pre-flight（準備作業） — 人設鎖定（Persona Lock）、瀏覽器工具、URL、視埠、能力測試
2. Discovery（探索階段） — 網站地圖、任務流程清單、元素清單
3. Walkthrough（走查階段） — 互動清單、任務流程、元素窮舉、多面板壓力測試、首次使用者視角、即時互動冒煙測試
4. Polish（修飾階段） — 視覺細節巡檢、元件完美度檢核表
5. Stress（壓力測試） — 情境測試套件（11 個情境）+ 擴充壓力測試配方
6. Verdict（裁定階段） — 裁定狀態、硬性門檻記分卡、完美度路線圖、附帶重現步驟的問題發現
7. Fix-and-verify（修復與驗證） — 修補問題、重新走查受影響區塊、更新報告

若需執行 30 秒的部署前快速檢查，請使用本檔案底部的 dogfood 演練——這屬於專案層級規則，而非 Skill 調用。

Phase 1 — Pre-flight（準備作業）

包含五個門檻。只要有任何一項未通過即停止執行。

1. 人設鎖定（Persona Lock）

審查在開始前最先需要確立角色人設。若缺乏鎖定的角色人設，問題發現容易流於空泛的「看起來沒問題」。

請按以下優先順序取得角色人設：

1. 引數（Argument） — 如果使用者有提供（例如："ux audit as a busy insurance broker"）
2. 專案角色人設 — 讀取現有的角色人設檔案（備用鏈：.jez/audit-personas/<slug>.md → docs/personas/<slug>.md → personas/<slug>.md → .audit/personas/<slug>.md）。以第一個比對成功的檔案為準。
3. 詢問一次 — "請問是誰在存取這個應用程式？他們想完成什麼任務？"

擷取要點：角色、科技熟悉度、時間壓力、情緒狀態、裝置情境。優秀的人設能預測他們會忽略什麼細節（例如：「在接電話空檔操作的前檯人員不會向下滑動到首屏以下」）。

將選定的角色人設寫在審查報告頂端以完成鎖定。每項問題發現都必須站在該角色的立場上具備合理說服力。若你發現自己冒出 "開發人員應該知道..." 的想法——請立刻打住。你設定的角色人設並不知道。

在所有多頁面功能中，務必同步套用首次使用者視角（強制執行，詳見 Phase 3），即使明確設定的人設是其他角色亦然。這是 AI / 內部工具最容易忽略的盲點。

角色人設庫與撰寫規範請參閱 references/persona-lock.md。

2. 瀏覽器工具（Browser tool）

目標	工具	原由
需驗證的應用程式	Chrome MCP	直接使用你真實登入的 Chrome 工作階段——OAuth、Cookies、RBAC 皆可直接運作
公開網站	Playwright MCP	無需登入
兩者皆無法使用	停止執行	請使用者連接 Chrome MCP 或安裝 Playwright

切勿在未告知情況下退回使用全新的 Playwright 工作階段來測試需驗證的應用程式——若無法登入，審查將完全失去價值。若 Chrome MCP 未連接，請停止並提示："請開啟 Chrome，在 Claude 擴充功能中點擊「Connect」，然後重新執行。"

命令說明請參閱 references/browser-tools.md。

3. URL

優先使用已部署/線上的版本——以取得真實的身分驗證、延遲、CDN 與 CORS 環境。探索方式：讀取專案 CLAUDE.md / README 尋找 "URL" → 檢查技術棧設定（wrangler.jsonc、vite.config.ts、next.config.js、config/database.yml、manage.py、.env 的 APP_URL、wp-config.php）→ 執行 lsof -i :PORT（常見埠號：5173 Vite、3000 Next/Rails、8000 Django/Laravel、8787 Wrangler、4321 Astro）→ 詢問使用者。技術棧專屬指引請參閱 references/project-adaptation.md。僅在使用者要求或功能尚未部署時才使用本機環境。

4. 視埠（Viewport）

開始時固定視窗尺寸為 1440×900。Phase 3 多面板壓力測試會涵蓋 375 / 768 / 1024 / 1280 / 1440 / 1920。切勿超過 2000px——否則會破壞測試架構。

5. 能力測試（Capability tests）

在開展任何走查前，請先驗證工具正常運作——各執行一次調用：

• 一次擷取畫面
• 一次讀取 Console
• 一次網路請求清單紀錄
• 一次元素選擇器查詢

若有任何一項失敗，請先停止並修復連線，再重新開始審查。無法讀取 Console 輸出的審查毫無價值。

Phase 2 — Discovery（探索階段）

網站地圖爬取（Sitemap crawl）

在審查任何頁面之前，建立完整的頁面清單。

1. 路由器設定 — 讀取應用程式的路由定義（React Router、TanStack Router、Next.js app 目錄）
2. 導覽爬取 — 逐一點擊側邊欄/選單的每個區塊與子區塊
3. 深層連結 — 位於 CLAUDE.md、說明文件或先前審查報告中的 URL

每個路由一行，並附上其用途：/app/clients — 客戶清單、搜尋、新增客戶。

任務流程清單（Thread inventory）

找出 3–5 個構成使用者日常工作的真實任務。這些是整個審查的核心主軸。

尋找方式：詢問使用者、閱讀 CLAUDE.md / README，或從頂層導覽列推導。範例：保險經紀人 → 保單續約、建立客戶、處理今日待辦佇列。專案管理工具 → 晨間分類、更新任務、傳送客戶摘要。空間 / 聊天應用程式 → 建立空間、傳送訊息、開啟討論串。

元素清單（Element inventory）

到達每個路由時，列出所有互動元素。請以延遲載入方式建立清單——在巡檢時按頁面逐步建立，而非一次全部預先建立。這將用於計算覆蓋率指標："已測試 /app/clients 上的 31 個元素中的 29 個"。

Phase 3 — Walkthrough（走查階段/審查本體）

互動清單（Interaction Manifest）（強制要求）

每次走查都必須產出互動清單。缺少清單時，裁定一律判定為 Incomplete。

INTERACTION MANIFEST — /dashboard/spaces/marketing-pod
  Persona: 中小企業主、時間緊迫、科技熟悉度低
  [✓] 14:32:01 在訊息輸入框輸入 "@assistant test" (textarea[placeholder*="message"])
  [✓] 14:32:03 從自動完成選單選取 @assistant (li[data-mention-id="assistant"])
  [✓] 14:32:05 點擊傳送 (button[aria-label="Send"])
  [✓] 14:32:06 驗證輸入框在 1000ms 內已清空 (textarea.value === "")
  [✓] 14:32:08 驗證訊息已出現在紀錄中 ([data-message-id] 數量 +1)
  [✓] 14:32:12 開啟該訊息的討論串 ([data-thread-trigger])
  [✓] 14:32:13 驗證開啟討論串後主欄位寬度 ≥ 200px (getBoundingClientRect().width)
  [✓] 每步完成後讀取 Console（0 個警告、0 個錯誤）
  [✓] 每步執行前後均擷取畫面
  [✓] 網路請求已列入清單（0 個 5xx，驗證頁面 0 個 403/404）

每個核取方塊皆需對應真實的工具調用（點擊、擷取畫面、讀取 Console），並記錄時間戳記與選擇器。Agent 若未附上完整清單，絕不可產出 "Pass" 報告。

每個受審頁面的必要紀錄項目：

• ≥ 1 個輸入框填入內容（真實文字，不能僅是點擊）
• ≥ 1 個主動作被觸發（傳送 / 儲存 / 送出 / 建立 / 發布 — 依情境而定）
• ≥ 1 個對話框（Modal）或詳細資訊面板被開啟
• 主動作執行後 ≥ 1 次 Console 讀取
• 主動作執行前與執行後各 ≥ 1 次畫面擷取
• 動作執行後的預期狀態驗證（輸入框清空、成功提示 Toast、路由變更、清單更新）

完整範本與重放協定請參閱 references/interaction-manifest.md。

任務流程遍歷（Thread Traversal）

針對每個任務流程：

1. 從應用程式入口點開始 — 切勿從中途開始。真實使用者只會停留在 / 或 /dashboard。
2. 以角色人設進行走查 — 若角色傾向粗略瀏覽，就粗略瀏覽。若角色會誤讀標籤，就模擬誤讀。記錄操作中的猶豫時刻。
3. 擷取每次狀態變更的畫面 — 預設狀態 → 懸停/聚焦（hover/focus）→ 作用中（active）→ 點擊後 → 載入後 → 確認畫面。底片式連續畫面即為證據。
4. 計算操作成本 — 點擊次數、決策點、死胡同、中斷恢復能力（在第 3 步關閉分頁並於第 4 步返回 — 狀態是否得以保留？）。
5. 在每個任務流程結束時將擷取畫面交付子 Agent 進行審查。

在每個任務流程結束時，以角色人設回答：結尾是否明確？我還會再使用嗎？改善哪一件事能讓流程簡易度加倍？

請參閱 references/walkthrough-checklist.md 與 references/workflow-comprehension.md。

元素窮舉（Element Exhaustion）

針對每個路由逐一檢核清單。可跳過已在任務流程遍歷中測試過的元素。詳細說明請參閱 references/walkthrough-checklist.md。