截圖轉Compose 是做什麼的?
在 Compose 中忠實重現設計,無需靠目測。參考圖就是驗收測試,因此你使用的每個數值要不是觀測值(從圖像上測量得出),就是推斷值(你聲明是猜測),最終完成的畫面會與參考圖進行比對。
當設計是輸入時
- 僅有截圖/示意稿:按照以下所有階段進行。
- 有 Figma 框架可用:跳過測量(從 Figma 讀取值),其餘步驟保留。
- 尚無設計:先使用
app-design-studio技能,再回到此處。
工作流程
在檔案中工作(docs/design/),一次處理一個螢幕,共用基礎設施建立完成後再進行。在理解整個螢幕清單之前,不要實作任何東西。
- 檢查。 先閱讀儲存庫(架構、主題、共用元件、現有畫面)。保留可行的部分。記錄假設。
- 清單。 將參考圖完整複製到
docs/design/reference/(使用 kebab-case 命名)。撰寫SCREEN_INVENTORY.md:每個圖像對應一個畫面 + 狀態、畫面之間的連結、缺失的參考(有連結但未顯示的畫面)、像素尺寸和長寬比。包含所有狀態:載入中、空白、錯誤、離線、權限、付費。 - 測量。 執行
scripts/measure_image.py shot.png --frame-dp 390 --sample x,y ...取得 px 轉 dp 的比例和顏色樣本(references/measuring.md)。像素不等於 dp:除非另有說明,否則假設一個 390 dp 的框架,dp = px / (imageWidthPx / 390)。在單獨的欄位中記錄觀測值和推斷值。 - 設計系統。 將測量到的顏色映射到 Material 3 角色、字型比例、形狀、間距主題。畫面只使用主題代號(畫面中沒有十六進位顏色、尺寸或圓角)。定義淺色和深色;如果只有淺色,則推導深色而不改變佈局。
- 素材(
references/assets.md)。圖示:一個系列,從 Iconify 獲取,使用scripts/svg_to_vectordrawable.py轉換。美術圖:生成它,絕不從截圖中裁剪。文字、按鈕、卡片、環形圖和圖表始終使用 Compose,絕不使用圖像。在ASSET_INVENTORY.md中記錄來源、授權、模型和提示詞。 - 計劃。 預先為每個畫面決定:返回行為、網路/離線類別、權限、小螢幕上的滾動或適配、動畫。撰寫
SCREEN_IMPLEMENTATION_PLAN.md並指定建置順序。(這些品質規則位於android-compose-quality-gate技能中。) - 實作,首先建立共用基礎,然後是畫面:無狀態可組合項搭配不可變的 UI 狀態、帶有意圖的 ViewModel、每個檔案一個可組合項、所有文字使用字串資源。僅對具有不相關檔案的獨立模組進行平行化。在建立卡片、瓷磚或緊湊文字之前,先閱讀
references/compose-lessons.md。 - 比較(
references/verification.md)。渲染畫面(模擬器截圖或 Roborazzi),使用scripts/compare_side_by_side.py將它與參考圖以相同寬度並排放置,列出佈局、間距、字型、顏色、形狀和素材的差異,修正,重複。然後檢查小裝置(360 x 526 dp)、長文字/德文、RTL、深色、字型縮放 1.3。絕不為了像素匹配而犧牲功能或響應性。 - 交付。 保持參考圖、附提示詞的素材、圖示來源/授權、清單和比較註記是最新的。一個畫面只有在它能運作並且通過視覺比較時才算完成。按主題提交。
防止常見失敗的規則
- 絕不從參考截圖中裁剪圖像(低解析度、壓縮、內嵌 UI)。
- 絕不用圖片代替原生 UI。
- 當參考圖不明確時,不要憑空發明設計:做出最合理的推斷,將其寫入推斷欄,保持貼近參考圖。
- 在畫面經過執行和比較之前,不要宣稱完成。
- 儲存庫或文件中沒有秘密(API 金鑰);圖像服務金鑰來自環境變數。
檔案
references/measuring.md- px 轉 dp、顏色取樣、觀測值與推斷值表格。references/assets.md- Iconify 轉 VectorDrawable、圖片生成順序與審查、匯出尺寸、其他來源。references/compose-lessons.md- 耗費實際時間的缺陷:同級卡片比例、內建測量崩潰、寬度閾值、自動調整文字大小。references/verification.md- 模擬器與 Roborazzi 比較循環及裝置矩陣。scripts/measure_image.py,scripts/svg_to_vectordrawable.py,scripts/compare_side_by_side.py(Python 3 + Pillow)。