joo6077/設計審計

陷阱

1. 禁止評估程式碼品質 — 請勿評估架構、效能或程式碼風格。僅判定是否符合設計原則。

2. 禁止濫用「未使用 Token」失敗 — 對於沒有設計 Token 的專案，請勿濫用「未使用 Token」作為失敗理由。如果沒有 Token 系統，請留下建議使用 design-system 技能的備註。

3. 無障礙類別為必填 — 即使看起來沒有視覺問題，也必須檢查：對比度 (WCAG 2.2 AA 4.5:1)、觸控目標、焦點指示器、表單標籤連結、WCAG 2.2 新增的成功準則 (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA)。省略則拒絕。

   觸控目標標準整理 (2026-04-11 更新):

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (例外：足夠間距 / 內聯文字 / 使用者代理 / 必要時)
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = 觸控裝置實用建議值 (平台指南)

   若在既有報告中僅標示「44×44pt」，讀者可能會誤解為「WCAG AA 要求」，因此必須區分 AA / AAA / 平台建議。來源：W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2。

4. 包含 AI 反模式檢查 — 必須包含真實性類別。統一的 border-radius、通用的藍紫色調色盤、相同結構的重複、無目的的裝飾效果均為失敗原因。

5. 嚴重程度分類為必填 — 每個失敗項目都必須標示嚴重程度：Critical (無障礙·倫理), Major (層級·一致性), Minor (細部調整)。缺少嚴重程度的失敗報告視為不完整。

6. 禁止主觀判斷 — 「看起來不錯」、「這樣還可以」不能作為依據。所有 PASS/FAIL 必須基於 audit-criteria.md 中定義的原則與數值標準。

7. 包含狀態/例外畫面 — 請勿僅檢查預設畫面。若程式碼中存在空狀態、錯誤狀態、載入狀態、資料過多/過少狀態，則一併檢查。

8. 區分無法確認的項目 — 對於執行時期渲染、實際互動等靜態分析無法判斷的項目，請標示為 [未驗證] 而非 PASS/FAIL，並說明手動檢查方法。

9. 禁止混淆啟發式與類別 — Nielsen 10 項啟發式是評估觀點框架。實際判斷必須對應至 audit-criteria.md 的 10 個類別標準 (Typography, Color, Spacing, Accessibility, Interaction, Motion, Visual Hierarchy, Layout & Grid, Ethical Design, Authenticity) 來執行。

10. 逐規則審計 — 宣告完成前遍歷 10 個類別 — 在做出 APPROVE/REJECT 判定前，必須遍歷 audit-criteria.md 的 10 個類別 × 核心檢查點，並在報告中以表格形式明確標示每個項目的 PASS / FAIL / [未驗證]。請勿將部分類別含糊歸類為「不適用」——必須說明理由。跳過類別的審計不算是審計 (skill-design-guide §3.6 逐規則審計)。

11. 二進位可判定性預檢 — 開始審計前確認二進位判定可能性 — 確定審計範圍後，先檢查每個預期 FAIL 項目是否「僅憑程式碼/樣式/Token 即可做出 PASS/FAIL 的二進位判定」。需要執行時期渲染、實際互動、MCP Figma 比對的項目，應立即分類為 [未驗證]，切勿將其當作 PASS 通過。未驗證分為兩個計數器 — invalid_evidence ([未驗證:INVALID] · 無後綴的 [未驗證]) 計為 0 件一般判定、1 件允許 PASS 但須加註警告、2 件以上即使沒有個別 FAIL 也直接 REJECT。滿足 4 項條件的 [未驗證:ENV] 則以 env_gaps 另行計算，不計入 REJECT 判斷；若 verified_coverage 低於 0.60 則為 BLOCKED。此規則以 harness/docs/guides/qa-evaluation-guide.md §標準未驗證證據協定 中的「閾值 2」條款為正本，此處不再重新定義。應與 design-reviewer 規則 8 副本保持一致 (agent-design-guide §3.5 二進位可判定性 · 技能端對應)。

12. 證據有效性門控 — 「有證據」與「證據能證明」是不同的 — 若陷阱 11 處理的是能否取得證據，則此項處理的是雖然取得了證據，但該證據無法證明任何事情的情況。在確定 PASS 之前，必須通過 4 項檢查。只要有一項失敗，則結果不是 PASS 而是 [未驗證]。

    #	檢查	失敗範例 (審計脈絡)
    1	非空白	引用 0 位元組快照、僅含錯誤的日誌作為證據
    2	啟用	對比檢查的目標文字節點為 0 個，卻宣稱「無對比違規 PASS」
    3	可否證性	使用在任何程式碼中都會產生相同結果的 grep 作為 oracle
    4	來源	採用實作者註解或提交訊息中的「已確認無障礙」作為證據

    0 匹配判定 — grep 結果 0 件有兩種情況。有意的 0 (先統計目標檔案數，確認模式在其他位置有匹配後的 0) 才能作為 PASS 的依據。空泛的 0 (路徑錯誤、空檔案、絕對不會匹配的模式) 則屬於測量失敗，應標示為 [未驗證]。在證據陳述中，必須以 目標 N 個檔案 · 模式有效性確認 · 匹配 0 的形式一併寫出三者。

    渲染產物特別規則 — 僅包含空白畫面、空白列表、或預留位置的截圖，不是 PASS 的證據，而是驗證失敗的信號。將截圖作為證據時，必須指出條件所要求的具體元素。若無法指出，則視為無效證據。每個截圖都應參照 ../../references/visual-change-protocol.md §3 截圖檢查清單 (溢出、破損字形、晶片/徽章與換行、除錯重疊)，只要有一個截圖不符合，就不能作為 PASS 的證據。來源：harness/docs/guides/qa-evaluation-guide.md §證據有效性門控。

13. 前後對比審計 — 意圖外的區域變化視為 FAIL — 在審計變更 (git diff 基準) 時，請勿僅看靜態狀態，還必須對比請求範圍與實際變更範圍。若請求指定某個視覺屬性 (僅邊框、僅顏色、僅間距)，但同一元素連同 background / fill / radius / shadow / spacing / typography 一起改變，則視為 Major FAIL。若有已批准的設計稿或既有應用色彩，卻被替換為專案 Token 或預設色盤，則視為 Major FAIL (優先順序違規)。審計報告應以 EVIDENCE 區塊 (before / after / proof / 意圖外區域) 結尾。詳細資訊：../../references/visual-change-protocol.md。

14. 決策傳播覆蓋率 — 已確認的決定僅套用於部分畫面視為 Major FAIL — 若 .design/decisions.yaml 存在，應在 10 類別審計之前判定覆蓋率 (不增加類別——這是前提條件檢查)。對於每個 status: approved 的 decision_id，遍歷其 required_surfaces[]：(a) 若既無 golden 也無 user-visible assertion 則 FAIL、(b) 若僅有 golden 但缺少 visible/count/height assertion 則 FAIL、(c) 若 excluded_surfaces 中缺少理由的畫面視為覆蓋率缺口而 FAIL。嚴重度為 Major，若為無障礙/倫理決定則為 Critical。status: superseded (已取代) 的決定不判定畫面位置，僅檢查 superseded_by 是否指向同一清單中其他 approved 決定。若 manifest 本身不存在，則不是 FAIL，而是回報 NO_MANIFEST 並將其排除在審計範圍之外——目標 0 件與通過是不同的。結構定義、規則 4 條、可執行的檢查器：../../references/visual-change-protocol.md §6 決策傳播 Manifest。

15. 明確標示證據管道 — 請勿以 artifact_snapshot 判定應用畫面 — 所有引用的證據都必須附加管道名稱 (artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible)。PASS 陳述中必須包含 viewport、route/state、visible locator、count/height、screenshot/golden id 這 5 個元素，缺少任何一個則結果不是 PASS 而是 [未驗證]。管道定義：../../references/visual-change-protocol.md §7 證據管道。當使用者失敗報告與自身證據衝突時的協定，以 harness/docs/guides/skill-design-guide.md §3.8 及 harness/docs/guides/agent-design-guide.md §10 為正本，此處不重新定義——請勿以審計報告反駁使用者觀測。

流程

步驟 1：決定目標範圍與模式

根據使用者指定的路徑與模式來決定審計範圍：

• 檔案路徑 → 僅該檔案
• 目錄路徑 → 其下所有 UI 相關檔案
• 未指定 → 最近變更的 UI 檔案 (以 git diff 為基準)

模式：

• quick (預設) — 快速檢查全部 10 個類別。專注於 Critical/Major 失敗。
• deep — 完整檢查狀態/例外畫面、響應式 breakpoint、深色模式、無障礙細項。

步驟 2：確認審計類別

依序檢查 10 個類別。每個類別的核心檢查點：

類別	核心檢查點	嚴重度標準
Typography	字體級距一致性、行高 (依書寫系統範圍 — references/audit-criteria.md 行高比例行)、內文最小 14px (行動裝置)/16px (網頁)	Major
Color	文字對比 WCAG 2.2 AA 4.5:1、使用語意 Token、深色模式對比維持、使用 OKLCH/P3 wide gamut 時確認 sRGB fallback。APCA Lc 參考 (參考用): 內文 Lc 75~90、非內文 Lc 60 以上、Lc 15 以下為不可見。APCA 要求依字體大小+粗細的差別對比，因此細體字需要更高對比。判定標準為 WCAG 2.2 AA，APCA 為 WCAG 3.0 WD 參考用	Critical(對比) / Major(Token)
Spacing	間距級距一致性、觸控目標 WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44)、群組間/內邊距層級	Critical(觸控) / Major(級距)
Accessibility	禁止僅以顏色傳達狀態、焦點指示器、表單標籤、替代文字、WCAG 2.2 SC 2.4.11 Focus Not Obscured (AA)、SC 2.5.7 Dragging Movements (AA)、SC 3.3.8 Accessible Authentication Min (AA)	Critical
Interaction	動作回饋、載入指示器、錯誤顯示、取消/回復路徑、針對僅支援拖曳的 UX 提供 single-pointer 替代 (WCAG 2.2 SC 2.5.7)	Major
Motion	動畫目的性、持續時間 200~500ms、支援 prefers-reduced-motion	Major
Visual Hierarchy	標題/內文/標題比例差異、核心內容對比強調、群組邊距分離	Major
Layout & Grid	網格對齊、gutter 一致性、主要 breakpoint 響應式策略、元件層級響應式建議使用 container-type: inline-size + @container (容器查詢支援：Chrome 105 · Firefox 110 · Safari 16)。Container Queries 檢查： 頁面層級分支使用 media queries，元件層級分支確認是否使用 container queries。建議使用 cqw/cqi 單位，根據內容斷點設定 breakpoint (非以裝置為目標)	Major
Ethical Design	12 種暗黑模式模式不存在、同意明確性、註冊/取消路徑對稱性	Critical
Authenticity	相同結構重複 3 次以上、通用色盤、無目的裝飾、通用文案、與既有畫面慣例不一致	Minor~Major

步驟 3：呼叫 design-reviewer 代理器

使用 Agent 工具來建立 design-reviewer 子代理器：

Agent 工具呼叫：
- subagent_type: design-reviewer
- prompt: "請對下列檔案依設計原則進行 [quick|deep] 模式評估：[目標檔案清單]"

代理器以唯讀方式分析後，回傳各類別的 PASS/FAIL/未驗證結果。

步驟 4：報告格式化

將代理器結果整理為 templates/audit-report.md 格式。

每個 FAIL 項目必須包含：

• 檔案:行號位置
• 嚴重程度 (Critical / Major / Minor)
• 違反的原則 (含來源)
• 具體改善方向 (與技術堆疊無關)

若有 1 件以上未驗證項目，報告中必須一併附上有效性統計 (陷阱 12)：

## Evidence Validity
- 檢查目標證據數：{{n}} 件
- 判定無效：{{k}} 件 [項目 ID — 失敗的檢查編號 — 原因]
- 未驗證累計：`invalid_evidence` {{a}} 件 / `env_gaps` {{b}} 件 / `verified_coverage` {{c}}

步驟 5：最終判定

• FAIL 0 + invalid_evidence 0 + verified_coverage 0.60 以上 + L3 10/10 → APPROVE (記錄 env_gaps 數量)
• Decision Propagation Coverage FAIL 1 個以上 → REJECT (與 10 類別判定分開的前提條件——陷阱 14。manifest 不存在不是 FAIL，而是回報 NO_MANIFEST)
• 決策傳播檢查結束碼 2 (SCHEMA_ERROR) 表示輸入格式錯誤無法判定，因此為 REJECT——即使 violations=0 也不視為通過。結束碼 3 (NO_SURFACE · NO_DECISION) 與 NO_MANIFEST 同樣回報為目標 0 件
• Critical FAIL 1 個以上 → REJECT (立即)
• 僅有 Major/Minor FAIL → REJECT + 依優先順序列出改善清單
• FAIL 0 但 invalid_evidence 2 件以上 → REJECT (陷阱 11 閾值)
• FAIL 0、invalid_evidence 少於 2 件、verified_coverage = (判定的檢查項目數 − env_gaps) / 判定的檢查項目數 < 0.60 → BLOCKED (insufficient_verified_coverage——重新執行驗證命令後再審計)
• 即使 FAIL 0，但 L3 覆蓋率 < 10/10 (10 個類別中有跳過的類別) → REJECT + 標示剩餘類別 (跳過的類別即為 FAIL——審查者規則 11)
• FAIL 0、invalid_evidence 1 件、verified_coverage 0.60 以上、L3 10/10 → APPROVE + 標示未驗證項目與手動檢查方法

REJECT 報告結構：

1. Critical FAIL 清單 (需立即修正)
2. Major FAIL 清單 (下一個衝刺前修正)
3. Minor FAIL 清單 (建議改善)
4. [未驗證] 項目 (需手動確認 — 區分 [未驗證:ENV] / [未驗證:INVALID])

若是變更審計 (以 git diff 為基準)，報告結尾須加上 EVIDENCE 區塊 (陷阱 13)：

## EVIDENCE
- before: [變更前狀態依據 — 檔案:行號或截圖]
- after:  [變更後狀態依據]
- proof:  [支援判定的指令與輸出]
- 意圖外區域: [確認無變化的依據 / 或已處理為 FAIL 的項目]

參考資料

• references/audit-criteria.md — 各類別審計標準詳細說明
• templates/audit-report.md — 報告輸出格式
• ../../references/visual-change-protocol.md — 視覺變更優先順序、部分變更隔離、證據區塊、§6 決策傳播 Manifest、§7 證據管道 (SSOT)
• harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 — 使用者失敗報告優先順序協定的正本
• harness/docs/guides/qa-evaluation-guide.md §標準未驗證證據協定 · §證據有效性門控 — 未驗證閾值、有效性 4 項檢查的正本