Communitygithub.com

m3-design-review

根據 Material Design 3 審查使用者介面(螢幕截圖、HTML/CSS/JS、渲染頁面),並回傳一份附有測量或估算證據的編號、可決策報告。僅供審查使用。

m3-design-review 是什麼?

此 AI Agent 技能「m3-design-review」旨在對現有 UI 進行嚴格且系統化的 Material Design 3 (M3) 合規性審查。它透過層級規則(從無妥協的無障礙最低標準 Floor 規則,到專案自訂指南,再到 M3 核心與表達性層級)來評估 UI,並依據「嚴格」或「啟發式」兩種模式判定問題的嚴重性。其獨特之處在於要求提供經測量(渲染頁面、原始碼)或估算(影像)的證據,並明確標示證據類型。技能最終會產出一個結構化的編號報告,並引導使用者逐項決定接受或拒絕偏差,最終將決定記錄到決策總帳中,確保審查過程的可追溯性與一致性。此技能適用於 Web、Android、Flutter、iOS 等平台,並能與專案既有設計指南整合。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sbk-jdm/m3-skills/tree/HEAD/skills/m3-design-review

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Material Design 3 審查

根據 Material Design 3 (M3) 審查使用者介面,並尊重專案自身的設計指南,產出使用者可以逐項決策的編號報告。然後記錄決策並輸出已接受的變更。

使用時機 / 不使用時機

使用時機: 使用者要求:

  • 「依照 Material 3 審查此畫面 / 頁面 / 元件」、「這是否遵循 M3?」、「M3 稽核」、「設計審查」
  • 檢查現有 UI 的觸控目標、對比度、字體尺度、色彩角色、形狀、間距或元件
  • 在發佈前,將螢幕截圖或運作中的頁面與 Material 指南進行比較
  • 決定哪些 Material 偏差要保留、哪些要修正

不使用時機:

  • 使用者想要產生新的 UI、建立主題或從頭開始編寫程式碼(例如「幫我做一個 M3 登入頁面」);此技能僅供審查,不負責產生
  • 目標設計系統明確不是 Material(例如 Apple HIG、Fluent,或沒有 M3 基礎的自訂系統),除非使用者只想進行最低層級的 Floor 檢查
  • 問題是單純的事實查詢(例如「FAB 的高度是多少?」);直接從參考檔案回答

審查期間不得修改程式碼。僅在使用者做出決策後且提出要求時,才修改程式碼。

層級與優先順序

依下列順序套用規則。較高層級優先於較低層級。

  1. Floor 規則,層級 F:無障礙與可用性最低標準(目標大小、對比度、焦點、標籤、文字縮放、減少動態效果)。絕不可協商。專案指南不能豁免。
  2. 專案指南與記錄決策,透過轉接器協定(references/adapter-protocol.md)找到。
  3. M3 核心,層級 C:角色、Token、字體尺度、形狀尺度、元件規格。偏離需要明確的決策。
  4. 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. 測量

優先測量,而非估算。順序如下:

  1. 有可用渲染頁面(Playwright、瀏覽器自動化工具、DevTools): 在頁面中評估 scripts/measure.js,並使用其 JSON 輸出(參閱 references/measurement.md 的「如何執行」和「輸出路徑與支援的規則」)。分別測量每個寬度和主題:來自轉接器的寬度和文字尺寸設定,否則測試一個緊湊寬度(例如 390 px)和一個擴展寬度(例如 1280 px),以及淺色和深色模式。
  2. 僅有原始碼可用: 讀取 CSS/HTML/JS 或元件程式碼;從中計算大小、顏色和圓角,並將結果標記為 measured-code。
  3. 僅有影像可用: 估算,標記為 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. 檢查、分類、分組

對於每個候選項目:

  1. 首先根據功能對控制項進行分類(CMP-01),然後找到規則。引用其 ID 和其 Source,與參考檔案中的完全一致。當多個規則重疊時(一個元件規則和一個 Floor 規則針對相同的目標大小),引用最具體的一個,並在其後列出其他規則(例如「也參閱 A11-01」)。
  2. 如果沒有規則 ID 支持它,則不要將其報告為 M3 發現。如果它違反了專案指南,或參考資料中沒有規則涵蓋的 WCAG 2.2 成功標準,則將其放入「專案與 WCAG 註記」(N-01…),並以指南章節或 WCAG 2.2 SC x.y.z 作為其來源(典型情況:缺少 lang 屬性、停用縮放的 viewport meta 標籤)。否則將其省略。
  3. 檢查總帳:已記錄的偏差不再報告(在一行中提及被抑制的項目數量)。
  4. 檢查專案指南:與層級 C 或 E 的衝突放入「決策候選項目」,而非發現項。如果專案選擇沒有可偏離的 M3 規則,則候選項目使用規則 ID none (project convention)。
  5. 分類:根據寬容模式分類層級(F、C、E)和類型(問題或建議)。在 inspired 模式下,僅當層級 C 的不匹配「損害可用性」(因此是問題)時,才將其視為問題:例如文字小於 12 px、控制項的目的或狀態不明確、佈局在支援的寬度下中斷。否則為建議。
  6. 分組:每個根本原因一個發現。當同一個問題出現在多個地方,或來自一個共享的元件、類別或 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 偏差:品牌藥丸按鈕,拒絕其餘部分」):

  1. 對於層級 C 或 E 規則的每個 deviation:以 references/adapter-protocol.md 的格式,在決策總帳中附加一個條目(日期、規則 ID、範圍、一行說明理由、發現項 ID)。層級 F 的發現項不能是偏差:將其記錄為 accepted risk,並在摘要行中繼續報告。如果不存在總帳,提議其路徑,並僅在使用者同意後才建立。
  2. 對於每個規則 ID 為 none 的決策候選項目…

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能