Material Design 3 審查
根據 Material Design 3 (M3) 審查使用者介面,並尊重專案自身的設計指南,產出使用者可以逐項決策的編號報告。然後記錄決策並輸出已接受的變更。
使用時機 / 不使用時機
使用時機: 使用者要求:
- 「依照 Material 3 審查此畫面 / 頁面 / 元件」、「這是否遵循 M3?」、「M3 稽核」、「設計審查」
- 檢查現有 UI 的觸控目標、對比度、字體尺度、色彩角色、形狀、間距或元件
- 在發佈前,將螢幕截圖或運作中的頁面與 Material 指南進行比較
- 決定哪些 Material 偏差要保留、哪些要修正
不使用時機:
- 使用者想要產生新的 UI、建立主題或從頭開始編寫程式碼(例如「幫我做一個 M3 登入頁面」);此技能僅供審查,不負責產生
- 目標設計系統明確不是 Material(例如 Apple HIG、Fluent,或沒有 M3 基礎的自訂系統),除非使用者只想進行最低層級的 Floor 檢查
- 問題是單純的事實查詢(例如「FAB 的高度是多少?」);直接從參考檔案回答
審查期間不得修改程式碼。僅在使用者做出決策後且提出要求時,才修改程式碼。
層級與優先順序
依下列順序套用規則。較高層級優先於較低層級。
- Floor 規則,層級 F:無障礙與可用性最低標準(目標大小、對比度、焦點、標籤、文字縮放、減少動態效果)。絕不可協商。專案指南不能豁免。
- 專案指南與記錄決策,透過轉接器協定(
references/adapter-protocol.md)找到。 - M3 核心,層級 C:角色、Token、字體尺度、形狀尺度、元件規格。偏離需要明確的決策。
- M3 表達性與可選項目,層級 E。切勿將其缺失報告為缺陷。
當專案指南或記錄決策與層級 C 或 E 規則衝突時,不要報告違規。僅在「決策候選項目」下列出該衝突一次(僅當它尚未記錄在總帳中時)。當它與層級 F 規則衝突時,報告層級 F 的發現,並在其證據中註明衝突的指南。
寬容模式
兩種模式。預設為 inspired。
strict(嚴格):每個層級 C 的不匹配都是問題;層級 E 項目為建議。inspired(啟發式):層級 C 的不匹配是建議,除非它們損害可用性(此時它們是問題);層級 E 項目僅在增加明確價值時才是建議。- 在兩種模式下,每個層級 F 的發現都是問題。
使用使用者指名的模式。如果專案指南指定了一種,則使用該模式。否則使用 inspired 並在報告標頭中說明。
證據標籤
每個發現和每個註記都必須標記下列其中一個:
measured-rendered(測量-渲染):從渲染頁面(DOM、計算樣式、點擊測試)讀取,並提供選取器與數值。measured-code(測量-程式碼):從原始碼或聲明的 CSS 讀取,但未在渲染頁面上確認。measured-simulation(測量-模擬):在模擬環境下的渲染頁面上測量(用於文字縮放的窄視口、模擬設定如深色模式、減少動態效果或強制色彩)。建議在實際裝置上確認。estimated(估算):從影像推斷。
將 v0.1 標籤 measured 視為 measured-rendered。當一個發現結合多種來源時,使用最弱的標籤。除非已知比例(以 CSS px 為單位的視口寬度和 devicePixelRatio,或已知的參考元素),否則切勿從螢幕截圖中給出確切的 dp 或 px 值。詢問一次比例,或者給出一個範圍並標記為 estimated。切勿從壓縮影像中給出確切的對比度比值;給出近似比值並標記為 estimated。
工作流程
步驟 0. 辨識審查標的
從提供的素材或透過一次詢問,確定以下內容:
- 審查內容:螢幕截圖、原始碼檔案、URL 或本地頁面、設計工具匯出
- 平台:Web、Android(Compose 或 Views)、Flutter、iOS、跨平台
- 外型尺寸與視窗尺寸類別:緊湊(< 600)、中等(600-839)、擴展(840-1199)、大或特大
- 主題:淺色、深色或兩者;是否具有高對比度、減少動態效果或應用程式內文字尺寸設定
如果審查標的顯示個人資料(姓名、金額、地址、訊息、健康或帳戶資料),請在回覆的頂部說明,並建議審查已模糊處理或示範狀態。不要將螢幕截圖或頁面資料儲存在檔案、記憶體或總帳中。僅引用辨識元素所需的最少文字。
步驟 1. 載入轉接器
遵循 references/adapter-protocol.md:尋找專案設計指南、決策總帳、慣例清單、變更清單格式以及審查設定(要測試的寬度和文字尺寸設定)。如果找不到,詢問一次一個簡短的問題;如果使用者未回答或表示沒有,則僅使用 M3 和預設值繼續。
設計摘要: 當提供或找到設計摘要時(來自 m3-design-brief,或任何具有驗收標準 AC-nn 的摘要),將其視為專案指南。其決策(B-nn)在其範圍內視為記錄決策(而非決策候選項目);其寬容模式、寬度和主題作為審查設定;層級 F 仍然優先。檢查每個 AC 並填寫報告的「摘要驗收標準」部分(通過、失敗或未檢查,並附上證據)。
步驟 2. 選擇寬容模式
strict 或 inspired(參閱寬容模式)。如果使用者或指南已經決定,則無需詢問。
步驟 3. 測量
優先測量,而非估算。順序如下:
- 有可用渲染頁面(Playwright、瀏覽器自動化工具、DevTools): 在頁面中評估
scripts/measure.js,並使用其 JSON 輸出(參閱references/measurement.md的「如何執行」和「輸出路徑與支援的規則」)。分別測量每個寬度和主題:來自轉接器的寬度和文字尺寸設定,否則測試一個緊湊寬度(例如 390 px)和一個擴展寬度(例如 1280 px),以及淺色和深色模式。 - 僅有原始碼可用: 讀取 CSS/HTML/JS 或元件程式碼;從中計算大小、顏色和圓角,並將結果標記為
measured-code。 - 僅有影像可用: 估算,標記為
estimated,如果確切數字很重要,則詢問比例。
設定檢查,在閱讀任何結果之前(measurement.md 的「設定檢查」):
- 以您打算測試的 CSS 寬度傳遞
expectWidth。 - 如果
warnings包含viewport-meta-missing或viewport-width-mismatch,則停止。頁面佈局在非預期的寬度(通常為 980 px),因此每個尺寸都是錯誤的。修正設定(設定視口,或注入與正式環境提供相同的 viewport meta 標籤),重新執行,然後才繼續。切勿報告此類執行的大小;如果正式環境本身缺少該標籤,則報告一次。
有效點擊區域(measurement.md 的「有效點擊區域」): 啟用 hitScan(預設)時,根據 hitWidth x hitHeight 判斷目標大小,而非視覺框。hitAreaVia 說明如何找到該區域(box、label、pseudo、probe);probe 說明點擊測試是否確認其為可點擊(ok)或不可點擊(covered、offscreen、limited:僅幾何形狀,在報告確切大小前請先確認)。
由 ::before/::after 放大的 pseudo 區域視為有效;檢查其框是否未被邊框縮小或被 overflow: hidden 的祖先裁切,並對可疑情況在程式碼中確認。
對於文字縮放,遵循 measurement.md 的「配方:200% 文字」(結果為 measured-simulation);對於選單、對話框、工作表、分頁、無線電按鈕群組和檢視變更,遵循 measurement.md 的「配方:焦點流程」。
將腳本輸出(包括 truncated、nonTextContrast、labelInName、ariaConflicts)視為候選項目,而非最終判定:根據對應規則逐一確認後再報告。樣式和動態效果未被測量;當它們重要時,請在程式碼中或透過互動檢查。
當腳本無法解析對比度(漸層、圖片或半透明背景)時,手動計算最壞情況(文字下方最深和最淺的色標,或與實際背景合成後的 Alpha 色彩),並將其報告為 estimated,同時附上使用的色標。對於 color-mix() 或 Alpha 文字顏色,使用最終合成顏色。如果頁面沒有深色變體,報告一次(theme parity 規則,位於 references/color.md),而非每個元素都報告。
步驟 4. 僅載入相關參考資料
漸進式揭露: 切勿載入所有參考檔案。根據畫面上的內容選擇。
| 畫面包含 | 載入 |
|---|---|
| 任何畫面(總是) | 首先載入 references/layout-interaction-a11y.md,章節「無障礙 Floor 規則」和「跨元件規則」 |
| 色彩、主題、深色模式、Token、對比度 | references/color.md |
| 排版、圓角、高程、間距、動態效果、圖示 | references/styles.md |
| 應用程式列、徽章、底部工作表、按鈕群組、按鈕、卡片、輪播、核取方塊、晶片、日期選擇器、對話框、分隔線 | references/components-1.md |
| 擴展 FAB、FAB 選單、FAB、圖示按鈕、列表、載入指示器、選單、導覽列 / 抽屜 / 導覽軌、進度指示器、無線電按鈕 | references/components-2.md |
| 搜尋、分段按鈕、側邊工作表、滑桿、Snackbar、分割按鈕、開關、分頁、文字欄位、時間選擇器、工具列、工具提示 | references/components-3.md |
| 表達性功能、彈簧動態效果、形狀變形,或使用者詢問表達性 | references/expressive.md |
| 撰寫報告 | references/report-template.md |
| 記錄決策、慣例、變更清單 | references/adapter-protocol.md |
在大型檔案內,僅讀取畫面上元件的相關章節。首先列出標題(grep -n '^## ' references/components-1.md),然後僅讀取那些行範圍(sed -n 'START,ENDp' file)。如果參考檔案遺失,請說明並繼續使用其他檔案;不要為了填補缺口而發明規則。
步驟 5. 檢查、分類、分組
對於每個候選項目:
- 首先根據功能對控制項進行分類(CMP-01),然後找到規則。引用其 ID 和其
Source,與參考檔案中的完全一致。當多個規則重疊時(一個元件規則和一個 Floor 規則針對相同的目標大小),引用最具體的一個,並在其後列出其他規則(例如「也參閱 A11-01」)。 - 如果沒有規則 ID 支持它,則不要將其報告為 M3 發現。如果它違反了專案指南,或參考資料中沒有規則涵蓋的 WCAG 2.2 成功標準,則將其放入「專案與 WCAG 註記」(
N-01…),並以指南章節或WCAG 2.2 SC x.y.z作為其來源(典型情況:缺少lang屬性、停用縮放的 viewport meta 標籤)。否則將其省略。 - 檢查總帳:已記錄的偏差不再報告(在一行中提及被抑制的項目數量)。
- 檢查專案指南:與層級 C 或 E 的衝突放入「決策候選項目」,而非發現項。如果專案選擇沒有可偏離的 M3 規則,則候選項目使用規則 ID
none (project convention)。 - 分類:根據寬容模式分類層級(F、C、E)和類型(問題或建議)。在
inspired模式下,僅當層級 C 的不匹配「損害可用性」(因此是問題)時,才將其視為問題:例如文字小於 12 px、控制項的目的或狀態不明確、佈局在支援的寬度下中斷。否則為建議。 - 分組:每個根本原因一個發現。當同一個問題出現在多個地方,或來自一個共享的元件、類別或 Token 時,報告一次,並附上計數和每個出現的位置(或兩三個範例加上總數:「14 個 32 x 32 px 的圖示按鈕,例如
.toolbar button、#close」),以便單一決策即可涵蓋。將發現項放在修正所影響的區域。
按影響排序:首先是層級 F 問題,然後是影響任務完成的問題,然後是層級 C 問題,最後是建議。在群組內,按影響範圍排序(影響多少個元素或畫面)。報告上限約為 25 個發現;如果更多,說明被省略的數量,並提供進行第二輪審查的選項。
如果問題很少或沒有問題,直接說明。不要添加填充的讚美。不要為了填滿報告而發明問題。
步驟 6. 呈現報告
嚴格使用 references/report-template.md。每個發現項包含:執行中 ID(F-01,而非層級)、區域、層級與類型、證據(選取器或影像區域、數值、證據標籤、出現次數)、規則 ID 及其來源、重要性說明(一行,先說明使用者影響)、具體的建議變更(例如 min-height: 48px、color: var(--md-sys-color-on-surface-variant)、「角落特大,28dp」;切勿使用「改善對比度」)、工作量(S:一個屬性或 Token,M:一個元件或多個檔案,L:結構性或跨畫面變更)以及決策框。
報告標頭包含:審查的標的與寬度、寬容模式、參考資料的快照日期(已載入的參考檔案標頭中最舊的「快照日期」)、是否找到專案指南與總帳,以及證據組合(四個標籤各自的計數)。如果包含設計摘要,則失敗且違反規則的 AC 也是一個發現項(或註記);其 AC 行指向該 F-nn/N-nn,而非重複證據。
新鮮度: 將快照日期與今天日期進行比較。如果超過 6 個月,或使用者提到較新的 Material 版本,請在標頭中說明,建議在實施層級 C 變更前先更新參考資料(儲存庫的 maintenance/UPDATING.md),並提供先針對 https://m3.material.io/ 驗證受影響規則的選項。無論快照年齡為何,層級 F 的發現項均維持不變。
步驟 7. 套用決策
當使用者回覆時(例如「接受 F-01 至 F-05,F-07 偏差:品牌藥丸按鈕,拒絕其餘部分」):
- 對於層級 C 或 E 規則的每個
deviation:以references/adapter-protocol.md的格式,在決策總帳中附加一個條目(日期、規則 ID、範圍、一行說明理由、發現項 ID)。層級 F 的發現項不能是偏差:將其記錄為accepted risk,並在摘要行中繼續報告。如果不存在總帳,提議其路徑,並僅在使用者同意後才建立。 - 對於每個規則 ID 為
none的決策候選項目…