screenshot-to-compose (截图转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 状态上的无状态 Composable、带 Intent 的 ViewModel、每个文件一个 Composable、所有文本使用字符串资源。仅在互不冲突的文件之间并行化独立模块。在构建卡片、磁贴或紧凑文本之前,阅读
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)。